Oracle BRM Managing Customers
Oracle BRM Managing Customers
Oracle BRM Managing Customers
May 2012
Oracle Communications Billing and Revenue Management Managing Customers, Release 7.5 E16700-02 Copyright 2011, 2012, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Contents
Preface ............................................................................................................................................................... xxi
Audience..................................................................................................................................................... Downloading Oracle Communications Documentation .................................................................... Documentation Accessibility ................................................................................................................... Document Revision History .................................................................................................................... xxi xxi xxi xxi
Part I
About Account Balances ......................................................................................................................... 2-2 About Account Locking .......................................................................................................................... 2-3 Making Notes About Customers ........................................................................................................... 2-3 Creating and Reviewing Notes in Customer Center .................................................................... 2-3 Creating General Account Notes.............................................................................................. 2-3 Creating Notes about Specific Actions .................................................................................... 2-4 Displaying Notes in Customer Center..................................................................................... 2-5 Customizing the List of Reasons for Account Changes ................................................................... 2-5 About Finding Accounts ......................................................................................................................... 2-6 How Searching Handles Text Characters....................................................................................... 2-7 Customizing Search ........................................................................................................................... 2-7 Finding Customer Accounts Using Opcodes................................................................................. 2-7 About Exporting Customer Information to a Non-BRM Database ................................................ 2-7 Typical Customer Management Tasks ................................................................................................. 2-7 What Your CSRs Need to Know about BRM Customer Management ...................................... 2-8 About Maintaining an Audit Trail of BRM Activity ......................................................................... 2-9 About Using Audit Trails ................................................................................................................. 2-9 About Accessing Audit Trails .......................................................................................................... 2-9 About Customer Center .......................................................................................................................... 2-9 Who Uses Customer Center?......................................................................................................... 2-10 Customizing Customer Center ..................................................................................................... 2-10 About Using Customer Center...................................................................................................... 2-10 Summary Tab .......................................................................................................................... 2-10 Balance Tab .............................................................................................................................. 2-11 Payments Tab ........................................................................................................................... 2-11 Product Tab............................................................................................................................... 2-12 Service Tab ................................................................................................................................ 2-12 Hierarchy Tab ........................................................................................................................... 2-13 Sponsorship Tab....................................................................................................................... 2-13 About Event Browser ..................................................................................................................... 2-13 About Dumping and Validating Account-Related Information .................................................. 2-14 About ADU Account Search.......................................................................................................... 2-14 About ADU Account Dump.......................................................................................................... 2-15 Limiting Dump Information by Specifying a Date Range................................................. 2-16 About Account Data Validation.................................................................................................... 2-16 Configuring ADU............................................................................................................................ 2-17
3 Customizing Registration
Standard Registration Information....................................................................................................... Limitations for Entering Account Data........................................................................................... How BRM Uses the Customers Language Setting....................................................................... Specifying How to Validate Customer Contact Information .......................................................... Specifying the Valid Login Name Format ...................................................................................... Specifying the Valid Password Format........................................................................................... Specifying the Valid Telephone Number Format ......................................................................... Specifying the US State Format........................................................................................................ Specifying the ZIP Code Format...................................................................................................... 3-1 3-1 3-2 3-2 3-2 3-2 3-2 3-3 3-3
iv
Specifying the Salutation Format..................................................................................................... 3-3 Specifying which Information is Required for Registration ........................................................ 3-3 Validating Data from Account Creation Applications ................................................................. 3-4 Credit Card Validation and Charge Options ...................................................................................... 3-4 Specifying the Account that Records Credit Card Validations ................................................... 3-5 Allowing Registration without a Credit Card ............................................................................... 3-5 Validating Credit Cards at Registration ......................................................................................... 3-5 Allowing Registration without Credit Card Validation............................................................... 3-6 Revalidating Credit Cards ................................................................................................................ 3-6 Charging Customers at Registration ............................................................................................... 3-7 Which Fees are Charged at Registration ................................................................................. 3-7 How General Ledger Revenue is Reported for Registration Charges ................................ 3-7 Customizing whether to Charge at Registration.................................................................... 3-8 Specifying Customer Account Defaults .............................................................................................. 3-8 Specifying the Default Account Currency...................................................................................... 3-8 Specifying the Default Country ....................................................................................................... 3-9 Changing the Account Number Format ......................................................................................... 3-9 Defining Customer Email Domain Names..................................................................................... 3-9 Specifying the Valid Expiration-Date Format............................................................................. 3-10 Specifying the Maximum Number of Months Allowed in Billing Cycles ................................ 3-10 Allowing Accounts To Be Created with Backdated Services or Resources ............................... 3-10 Controlling which Plans and Deals Are Available to Customers ................................................ 3-11 Options for Presenting Plans and Deals ...................................................................................... 3-11 Modifying Deals During Registration.......................................................................................... 3-11 Changing Plan and Deal Names and Descriptions.................................................................... 3-11 Creating New Registration Fields ...................................................................................................... 3-12 Checking for Duplicate Registrations ............................................................................................... 3-12 Validating Registration Numbers ...................................................................................................... 3-12 Encrypting Customer Data .................................................................................................................. 3-12 Exporting Registration Information to a Non-BRM Database ..................................................... 3-13 Customizing Automatic Account Creation (AAC) Information .................................................. 3-13 Creating Hooks to External Programs ............................................................................................... 3-13 Adding Custom Account Creation Steps before the Account is Committed......................... 3-13 Adding Custom Account Creation Steps after the Account is Committed............................ 3-13 Sending a Welcome Email Message ...................................................................................... 3-14 Sending Account Information to Your Application when an Account is Created................ 3-14 Sending Account Information to Your Application when an Account is Modified ............. 3-14 Returning a Point-of-Presence (POP) List ........................................................................................ 3-15 Creating Accounts in a Multidatabase System ................................................................................ 3-16 Getting a List of Databases ............................................................................................................ 3-16 Selecting a Database........................................................................................................................ 3-16
Installing Self-Care Manager ................................................................................................................. 4-2 Configuring the Application Server ..................................................................................................... 4-3 Setting up Apache Tomcat................................................................................................................ 4-3 Requirements............................................................................................................................... 4-3 Deploying Your Application with Apache Tomcat ............................................................... 4-3 Setting Up Oracle WebLogic ............................................................................................................ 4-3 Requirements............................................................................................................................... 4-3 Deploying Your Application with Oracle WebLogic ............................................................ 4-4 Setting Up IBM WebSphere.............................................................................................................. 4-4 Requirements............................................................................................................................... 4-4 Deploying Your Application with IBM WebSphere.............................................................. 4-4 Uninstalling Self-Care Manager ........................................................................................................... 4-5 Deploying Self-Care Manager ............................................................................................................... 4-5 Supporting Localized Versions of Self-Care Manager...................................................................... 4-5 Using Self-Care Manager ........................................................................................................................ 4-6 Setting Connection Parameters ........................................................................................................ 4-6 Specifying which Plan List to Display ............................................................................................ 4-7 Setting the Timeout............................................................................................................................ 4-7 Enabling a Single Login for Multiple Services............................................................................... 4-7 Optimizing Self-Care Manager Connection Pool Performance .................................................. 4-7 Adding a Service to the Self-Care Manager Home Page ............................................................. 4-8 Troubleshooting Self-Care Manager ................................................................................................... 4-8 Using the Default HTML Web Pages ................................................................................................ 4-10 Logging In ........................................................................................................................................ 4-10 Accessing Account Information.................................................................................................... 4-11 Finding or Searching for and Viewing Events..................................................................... 4-12 Applying Voucher Top-Ups................................................................................................... 4-13 Viewing Resource Reservation Details ................................................................................. 4-14 Viewing Invoices...................................................................................................................... 4-16 Viewing Account Activity ...................................................................................................... 4-16 Viewing Products Purchased ................................................................................................. 4-17 Paying Bills Online .................................................................................................................. 4-18 Viewing Service Details for a Bill Unit ................................................................................. 4-19 Viewing Bill Units in an Account .......................................................................................... 4-19 Changing Login Name, Password, or Account Status ....................................................... 4-20 Changing Web pages ............................................................................................................................ 4-21 Editing Self-Care Manager Files .................................................................................................. 4-21 Editing JSPs ...................................................................................................................................... 4-21 Modifying the Self-Care Manager WAR File .............................................................................. 4-22 Files Used by Self-Care Manager ....................................................................................................... 4-23 JSPs Used by Self-Care Manager................................................................................................... 4-23 HTML Pages Used by Self-Care Manager................................................................................... 4-24 Other Files Used by Self-Care Manager....................................................................................... 4-25
vi
Enabling the Welcome Message....................................................................................................... Customizing the Welcome Message Text....................................................................................... Disabling the Welcome Message ..................................................................................................... Using Variables to Insert Information into the Welcome Message ............................................ Changing the Welcome Message Subject Line .............................................................................. Changing the Welcome Message Sender Address........................................................................ Specifying the Welcome Message Location ................................................................................... Setting Up Introductory Messages........................................................................................................ Customizing the Introductory Message ......................................................................................... Using Variables to Insert Information into the Introductory Message ...................................... Changing the Introductory Message Location .............................................................................. Specifying an Introductory Message............................................................................................... About the Email DM Opcodes .................................................................................................. Using Multiple Welcome and Introductory Messages ......................................................................
5-1 5-2 5-2 5-2 5-3 5-3 5-3 5-3 5-3 5-4 5-4 5-4 5-5 5-5
vii
Customizing Login Names ..................................................................................................................... 7-4 Customizing Login Names ............................................................................................................... 7-5 Requiring Login Names for Email and IP Services....................................................................... 7-5 Creating Logins for Prepaid Services.............................................................................................. 7-5 Creating Logins for Email Services ................................................................................................. 7-6 Creating Passwords .................................................................................................................................. 7-6 Customizing Passwords.................................................................................................................... 7-6 Implementing Password Encryption .............................................................................................. 7-7 Creating Passwords for Prepaid Services....................................................................................... 7-7 Customizing Password Expiration.................................................................................................. 7-7 Tracking Customer Authentication and Authorization Records .................................................... 7-8 Specifying and Loading Verification Preferences ......................................................................... 7-8 Specifying the Account that Records Login Failures .................................................................... 7-9 Viewing Login Failures .................................................................................................................... 7-9 Authenticating Customers by Using Your Custom Application .................................................. 7-10 Authenticating User Actions ......................................................................................................... 7-10 Finding a Customers Account Information ............................................................................... 7-11 Customizing Authentication Checks ........................................................................................... 7-11 Enabling Duplicate Session Checking .................................................................................. 7-13
9-1 9-1 9-2 9-2 9-2 9-2 9-2 9-3 9-4 9-4 9-4 9-5 9-5 9-5 9-6 9-6 9-6 9-6
Updating the /config/payment Object ................................................................................... 9-9 Creating a New /config/payment Object............................................................................ 9-10 Viewing Payment Information for a Custom Payment Method....................................... 9-10 Using the Undefined Payment Method................................................................................ 9-10 Changing a Customers Billing Type................................................................................................. 9-11 Changing a Customers Billing Day of Month ................................................................................ 9-11 Prorating Fees for a Partial Cycle ................................................................................................. 9-11 Changing a Customers Billing Cycle Length ................................................................................ 9-11 Changing a Customers Bill Due Date .............................................................................................. 9-11 Changing a Customers Credit Limit ................................................................................................. 9-12 Handling Credit Limit Conflicts ................................................................................................... 9-12 Ignoring Credit Limits during the Rating Process ..................................................................... 9-13 Configuring the System-Wide Override Credit Limit........................................................ 9-14 Changing a Customers Credit Threshold ........................................................................................ 9-15 About Setting Credit Threshold Values....................................................................................... 9-15 About Alerting Customers when Credit Thresholds are Breached......................................... 9-16 When Credit Thresholds are Checked ......................................................................................... 9-16 About Credit Limit and Threshold Checking during Real-time Rating ................................. 9-16 About Credit Limit and Threshold Checking during Batch Rating ........................................ 9-17 About the Format of the XML Output File Name............................................................... 9-18 About Loading Notifications from Pipeline Manager to BRM ........................................ 9-18 Customizing Client Applications to Modify Fixed Thresholds ............................................... 9-19 Configuring Event Notification for Threshold Checking ......................................................... 9-19 Setting Up the Batch Rating Process to Perform Threshold Checking.................................... 9-19 Enabling Threshold Checking in Pipeline Manager ........................................................... 9-19 Configuring Batch Controller to Run load_notification_event ......................................... 9-20 Configuring Pipeline Manager to Perform Threshold Checking ..................................... 9-21 Customizing Credit Limits and Resource Consumption Rules ................................................... 9-22 How BRM Handles Consumption Rules and Credit Limits .................................................... 9-22 Changing Tax Exemption Information ............................................................................................. 9-23 Adding or Changing a VAT Registration Number ......................................................................... 9-24
ix
Validating Your Business Profile Configuration File Edits ............................................. Assigning Bill Units to Business Profiles....................................................................................... Changing a Bill Units Business Profile ..................................................................................... Getting Information about an Objects Business Profile ............................................................
Calculating Conditional Discounts when Canceling a Product...................................... Specifying to Delete Canceled Products............................................................................. How Products are Canceled ................................................................................................. Customizing Product Cancellation ..................................................................................... Customizing Product Pricing ........................................................................................................... Overriding a Product Price.......................................................................................................... Providing Product Discounts ...................................................................................................... Modifying Rates and Price Models in a Product...................................................................... How BRM Stores Customized Product Data ..................................................................... About Customized Product Validity .................................................................................. How BRM Cancels Base and Customized Products ......................................................... How BRM Rates Events with Customized Products........................................................ Managing Discounts ........................................................................................................................... Purchasing Discounts ................................................................................................................... About Purchasing Discounts in Mid Cycle........................................................................ How Discounts are Purchased............................................................................................. Validating Discount Dependencies ............................................................................................ Canceling Discounts ..................................................................................................................... Canceling Resource Sharing Group Owner Discounts .................................................... Rating Delayed Events for a Canceled Discount............................................................... About Canceling a Discount in Mid Cycle......................................................................... Specifying to Delete Canceled Discounts ........................................................................... How Discounts are Canceled ............................................................................................... Customizing Discount Cancellation ................................................................................... Modifying Discount Attributes................................................................................................... Changing Discount Quantity ............................................................................................... Setting Discount Status ......................................................................................................... Setting Discount Purchase, Cycle, and Usage Start and End Times .............................. How Purchase, Cycle, and Usage Validity is Modified ................................................... Customizing Snowball Discounts ....................................................................................... Managing Deals ................................................................................................................................... Purchasing Deals........................................................................................................................... How Deals are Purchased..................................................................................................... Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts . Modifying Deals ............................................................................................................................ Validating Changes to Deals ................................................................................................ How Deals are Modified....................................................................................................... Transitioning Deals ....................................................................................................................... Validating Deal Transitions.................................................................................................. How Deals are Transitioned................................................................................................. Customizing Deal Transitions.............................................................................................. Defining Deal Dependencies ....................................................................................................... About Deal Dependencies .................................................................................................... Enabling Deal Dependencies Validation............................................................................ How Deal Dependencies are Validated.............................................................................. Deal Dependency Validations Involving Inactive or CanceledProducts or Discounts ......
11-19 11-20 11-20 11-22 11-23 11-23 11-24 11-25 11-26 11-29 11-31 11-32 11-33 11-33 11-34 11-34 11-35 11-36 11-37 11-37 11-37 11-37 11-38 11-39 11-40 11-40 11-41 11-41 11-42 11-43 11-43 11-43 11-44 11-46 11-51 11-51 11-51 11-52 11-52 11-53 11-54 11-54 11-54 11-55 11-55 11-56
xi
How BRM Acts on Deal Dependencies for Inactive or Canceled Products and Discounts..... 11-56 Enabling Deal Dependency Validations for Inactive or Canceled Products and Discounts ... 11-57 Canceling Deals ............................................................................................................................. 11-57 How Deals are Canceled....................................................................................................... 11-58 Managing Plans ................................................................................................................................... 11-58 About Plan Transitions in BRM .................................................................................................. 11-59 Factors To Note About Plan Transitions in BRM .............................................................. 11-59 About Defining Plan Transition Rules in Pricing Center................................................. 11-60 About Providing Transition Rules Using Policy Opcode ................................................ 11-60 How BRM Transitions Accounts From Source Plans to Target Plans............................ 11-61 Customizing Plan Transitions Without Configuring /transition Objects ..................... 11-63 Customizing Account-Level Deals During Plan Transitions .......................................... 11-64 Defining a Generation Change for Plans ................................................................................... 11-64 How a Generation Change Works....................................................................................... 11-64 Configuring Services for a Generation Change................................................................. 11-65 About Backdating Subscription Actions ........................................................................................ 11-66 About Backdating Beyond the G/L Posting Date .................................................................... 11-67 How Effective Time is Used to Validate Backdating Operations .......................................... 11-67 Rerating of Events for the Backdated Period ............................................................................ 11-67 About Backdated Product, Discount, Deal, or Plan Purchase................................................ 11-68 How Sub-balance Buckets are Created for Backdated Product Purchase ..................... 11-69 How Cycle Fees are Calculated for Backdated Purchase or Activation ........................ 11-69 Backdating a Product, Discount, Deal or Plan Purchase.................................................. 11-70 About Backdated Product, Discount, or Deal Cancellation.................................................... 11-70 How Cycle Fees are Calculated for Backdated Cancellation or Inactivation................ 11-71 How Earned and Unearned Revenue is Set for Backdated Period................................. 11-71 Backdating a Product, Discount, or Deal Cancellation .................................................... 11-72 Getting Data about Deals, Products, Discounts, and Services ................................................... 11-72 Getting Plans, Deals, and Products for Purchase ..................................................................... 11-72 Getting a List of Deals, Products, Discounts, and Services..................................................... 11-73 Getting a List of Plans and Deals that an Account Owns ....................................................... 11-73 Reading Data for All Valid Purchased Products and Discounts............................................ 11-74 Finding Events Associated with Deals, Products, Discounts, and Services ......................... 11-76 Retrieving Product Details........................................................................................................... 11-76 Creating Customized /Product Objects .................................................................................... 11-77 Validation Rules for Products, Discounts, Deals, and Plans ...................................................... 11-78 Creating Custom Transition Types for Deals and Plans .............................................................. 11-78 Transition Type API Considerations ......................................................................................... 11-79
xii
Backdating Status Changes .................................................................................................... About Status Changes and Balance Impacts............................................................................... Billing Inactive Accounts ............................................................................................................... About Rating and Service Status .................................................................................................. About Plan Transitions and Service Status ................................................................................. Setting Permissions for Changing Account Status..................................................................... Scheduling Status Changes in Advance ...................................................................................... Automatically Inactivating and Closing Accounts .................................................................... Inactivating and Closing Accounts in Hierarchical Groups ..................................................... Reusing Login Names and Passwords from Closed Accounts or Canceled Services........... Changing Purchase and Cycle Start Time for Reactivated Products and Discounts ............ Allowing Active Services with Inactive Accounts ..................................................................... How BRM Changes Product Status.............................................................................................. How BRM Changes Discount Status............................................................................................ Setting Account, Service, and Bill Unit Status by Using Your Custom Application ............... Changing the Status of an Account, Bill Unit, or Service.......................................................... PIN_FLD_STATUS Field Values ........................................................................................... PIN_FLD_STATUS_FLAG Field Values ............................................................................ Deferred Actions .................................................................................................................... Setting, Resetting, or Unsetting a Deferred CLOSE.......................................................... Customizing Status Changes....................................................................................................... Inactivating Accounts that Exceed a Specified Limit............................................................... Managing Deferred Actions .............................................................................................................. Displaying Deferred Actions in Customer Center ................................................................... Managing Deferred Actions in Your Custom Application ......................................................... Scheduling Deferred Actions ...................................................................................................... Modifying Deferred Action Descriptions.................................................................................. Deleting Deferred Actions ........................................................................................................... Executing Deferred Actions ........................................................................................................ Performing Policy Checks before Scheduling Deferred Actions ...........................................
12-3 12-3 12-4 12-4 12-4 12-4 12-4 12-4 12-5 12-5 12-6 12-6 12-7 12-8 12-8 12-9 12-9 12-10 12-11 12-11 12-11 12-12 12-12 12-12 12-13 12-13 12-13 12-14 12-14 12-14
xiii
Mapping States to Statuses ............................................................................................................... About the Service State Mapping Configuration File.............................................................. Modifying State-to-Status Mapping ........................................................................................... Deleting State-to-Status Mapping............................................................................................... About Associating Services with Custom Life Cycles ................................................................. Associating Services with Custom Life Cycles ............................................................................. Associating Bill Units with the SLM Business Profile ................................................................ Making the SLM Business Profile Your System's Default Business Profile ......................... Validating AAA Requests for Services that Use Custom Life Cycles ....................................... Adding VALIDATE_LIFECYCLE Entries for the Sample Prepaid Service Life Cycle....... Configuring Customer Center to Display Custom Service Life Cycle States ......................... About the Sample Prepaid Service Life Cycle .............................................................................. About Triggering Sample Prepaid State Changes.................................................................... About the Sample Business Rules............................................................................................... About the Sample Service State-to-Status Mapping ................................................................
13-15 13-16 13-18 13-19 13-19 13-19 13-22 13-22 13-23 13-24 13-25 13-26 13-27 13-27 13-28
xiv
About Transferring Non-Currency Resources during Subscription Service Transfer 14-17 About Extending Sub-Balance Validity when a Subscription Service is Transferred . 14-18 How Non-Currency Resources are Consumed when a Subscription Service is Transferred . 14-19 How Non-Currency Resources are Rolled Over when a Subscription Service is Transferred 14-21 How Cycle Fees are Prorated when a Subscription Service is Transferred .................. 14-23 How Billing Time Discounts and Folds are Applied when a Subscription Service is Transferred 14-23 About Rating Delayed Events when a Subscription Service is Transferred ................. 14-23 How a Subscription Service Transfer Affects Account Migration.................................. 14-24 Configuring Sub-Balance Validity for Subscription Service Transfer............................ 14-24 Mapping Subscription Services in the Pipeline Manager Database ........................................ 14-26 About Billing for Subscription Service Usage .............................................................................. 14-26 About Creating Multiple Bills for a Subscription..................................................................... 14-27 About Billing for Multiple Subscriptions .................................................................................. 14-27 About Billing upon Subscription Service Cancellation ........................................................... 14-27 How an Account is Billed when a Subscription Service is Canceled during the Billing Delay Period 14-28 About Billing a Subscription Service after it is Transferred to Another Subscriber............ 14-29 Managing Subscription Services in Your Custom Application ................................................. 14-29 Creating a Subscription Service Group...................................................................................... 14-29 Creating Subscription Services in a Price Plan .................................................................. 14-29 Creating Subscription Services when Registering Customers ........................................ 14-31 Configuring ERAs for a Subscription Service........................................................................... 14-31 Associating a Device with a Subscription Service.................................................................... 14-32 Adding a Service to an Existing Subscription Service Group ................................................ 14-32 Canceling a Subscription Service................................................................................................ 14-32 Transferring a Subscription Service ........................................................................................... 14-33
xv
Changing the Owner of a Profile Sharing Group through a Customized Client Application ....... 15-8 Deleting Profile Sharing Groups ...................................................................................................... 15-9 Deleting a Profile Sharing Group through a Customized Client Application..................... 15-10
xvi
Understanding Brands ......................................................................................................................... About Brand-Aware Data .............................................................................................................. Brand-Aware Information ...................................................................................................... System-Wide Information....................................................................................................... About Organizing Brand Hierarchies ............................................................................................... About Naming Brands ................................................................................................................... About Brands and Account Groups ............................................................................................. When to Use Account Groups Instead of Brands ............................................................... About Creating Sub-Brands........................................................................................................... About Granting Access to Brands ...................................................................................................... About the Root Access Group ....................................................................................................... About Price Plans for Brands .............................................................................................................. About Brand Currency ................................................................................................................... About Closing, Inactivating, and Reactivating Brands ............................................................... About Duplicate Service Logins Across Brands ........................................................................... About Using Brands with Multiple Databases ............................................................................. About A/R Accounts and Brands ..................................................................................................... About Running Billing ......................................................................................................................
18-2 18-2 18-2 18-4 18-5 18-5 18-6 18-6 18-7 18-7 18-9 18-9 18-9 18-10 18-10 18-11 18-11 18-11
xvii
20 Managing Brands
Overview of Brand Administrator Tasks .......................................................................................... Creating a Price List for Brand Accounts .......................................................................................... Changing Account Defaults for a Brand........................................................................................... Creating a Brand-Specific Web Page ................................................................................................. Defining a Brand-Specific Invoice..................................................................................................... Defining a Brand-Specific General Ledger System ....................................................................... Defining Reports for a Brand.............................................................................................................. Creating CSR Accounts for a Brand................................................................................................... Creating Sub-Brands............................................................................................................................. Controlling Access to Sub-Brands and Account Groups .......................................................... Accessing Branded Customer Accounts ........................................................................................... Accessing Branded Customer Accounts in Customer Center .................................................. Processing Payments for Brand Accounts ........................................................................................ Inactivating or Closing a Brand .......................................................................................................... Preventing Duplicate Brand Names .................................................................................................. Changing the Brand of an Account by Using a Custom Application ......................................... 20-1 20-1 20-2 20-2 20-2 20-2 20-3 20-3 20-4 20-4 20-4 20-4 20-5 20-5 20-5 20-5
Part III
xviii
Supporting Delayed Billing ........................................................................................................... Improving Conversion Manager Performance ................................................................................ XML File Formatting ...................................................................................................................... Running Multiple Instances of the pin_cmt Utility.................................................................... Using Connection Pooling with Conversion Manager.............................................................. Configuring Log File Levels ........................................................................................................ System Resources .......................................................................................................................... Conversion Manager Preload Tuning........................................................................................ Increasing Memory Allocation to Prevent a System Hang ............................................. Conversion Manager Load Tuning ............................................................................................ Conversion Manager Deploy Tuning ........................................................................................
22-9 22-9 22-9 22-9 22-9 22-10 22-10 22-10 22-11 22-11 22-11
xix
About Partitioning ................................................................................................................................ About your Partitioning Scheme .................................................................................................. About Making Conversion Manager Partition Aware ................................................................... About the Timestamps Encoded in Object POIDs ..................................................................... Conversion Manager Tasks for Partitioned Storable Classes ................................................... About Configuring Conversion Manager to Encode Timestamps in POIDs ......................... Setting Up Your System to Load Legacy Data into Table Partitions ........................................... Creating Partitions for Your Legacy Data ................................................................................... Configuring Conversion Manager for Partitioning ................................................................... Configuring which Timestamp to Encode ........................................................................... Configuring the Number of POIDs to Reserve.................................................................... Passing Object Creation Timestamps in the Input XML File....................................................
26-1 26-1 26-3 26-3 26-3 26-4 26-4 26-5 26-5 26-5 26-6 26-7
Part IV Customer Management Utilities 27 Conversion Manager Utilities 28 Customer Management Utilities
xx
Preface
This document describes how to manage customers in Oracle Communications Billing and Revenue Management (BRM).
Audience
This document is intended for developers and system administrators.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc. Access to Oracle Support Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
Version E16700-01
xxi
Version E16700-02
Description Added information about the EventAdjustmentsDuringCancellation business parameter. Added the following for custom service life cycles:
xxii
Part I
Part I
About Registering Customers About Managing Customers Customizing Registration Setting Up Customer Self Care with Self-Care Manager Sending Registration Information to Customers Managing Customer Contact Information Managing Customer Authentication Creating and Managing Customer Segments Managing Customer Billing Information Managing Business Profiles Managing Customers Services and Products Changing Account and Service Status Managing Service Life Cycles Managing Customers Subscription-Level Services Working with Profile Sharing Groups Sending Email to Customers Automatically Managing System and Account Currencies
1
1
This chapter provides an overview of registering a customer in Oracle Communications Billing and Revenue Management (BRM).
About Registration
When you register a customer, you create a customer account in the BRM database. Registration typically follows this process:
1. 2. 3.
The customer calls the customer service representative (CSR). See "Ways to Register Customers". The customer chooses a plan. The customer provides information such as name, address, and credit card number. In addition, a CSR might give discounts to the customer or collect billing information such as the name of a billing contact. The account is created in the BRM database. At account creation, a number of events occur:
4.
The customer information is checked by BRM to see if it is valid and to make sure that all required information has been supplied. See "Specifying How to Validate Customer Contact Information". If the customer entered a credit card number, it is validated by a credit card processing service. See "Credit Card Validation and Charge Options". If there is a purchase fee, the customer is automatically charged. A welcome message is automatically sent to the customer. See "Sending Registration Information to Customers".
In Customer Center, you can backdate the account creation to a date earlier than the current date.
Give customers calling cards or voucher cards, which they use to access accounts you have already created in your BRM database.
1-1
You can implement both types of registration: by CSRs, and by the Web. Web-based registration takes longer to set up, but it is more cost effective. Complex plans are best offered by a CSR, who can explain the plans. If you use account groups, you might need a CSR to assign accounts to groups.
Use Self-Care Manager. You can customize the appearance of the default Web pages by modifying Java Server Pages (JSPs). A programmer can add functionality by modifying Self-Care Managers source code. See "Setting Up Customer Self Care with Self-Care Manager".
Create a Web interface by using the Portal Communications Module (PCM) library. If you use the PCM library, your Web server must run on a platform that supports BRM.
Add the new customer to an account group. Give the customer additional discounts on products. See "Managing Customers Services and Products". Change the account status or service status.
Information about special offers. The customers connection settings, such as news server address and mail server address. A list of phone numbers for dialup connections.
See "Sending Registration Information to Customers" for information about sending messages to your customer.
Use the business account method if you are creating an account for someone who runs a business, such as an Internet service provider (ISP) or an E-Commerce business. The business account method includes billing setup information such as billing cycle and accounting type. Use the consumer account creation method to create accounts for consumers. The consumer account creation method has fewer fields, which streamlines the account creation process.
You specify if a deal is customizable at account creation when you create the price list in Pricing Center.
You cannot inactivate a product after it has been purchased. However, you can inactivate a service.
Creating an Account
To create an account, use PCM_OP_CUST_COMMIT_CUSTOMER. The account creation process is:
1.
To backdate an accounts 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.
1-3
2. 3.
PCM_OP_CUST_CREATE_CUSTOMER calls the PCM_OP_CUST_PREP_ CUSTOMER opcode to validate the registration information. 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 storable object. Sets account credit limits. Purchases a deal. Creates a /service storable object. If the deal purchased for the account is a required deal, the /service objects 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 registration data, it calls a base opcode to cancel the transaction, ensuring that the customer objects are not created, and then returns the validated registration 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 registration information. In addition, PCM_OP_CUST_PREP_CUSTOMER calls the PCM_OP_PYMT_POL_ SPEC_VALIDATE policy opcode to determine whether a customers payment information needs to be validated during registration. If validation is required, PCM_OP_CUST_PREP_CUSTOMER calls the PCM_OP_PYMT_VALIDATE opcode to perform the operation. If validation fails, the results are transformed to be consistent with the results used to describe registration failure results and are then returned on the output flist. See "Changing How BRM Handles Paymentech Address Validation Return Codes" in BRM Configuring and Collecting Payments.
4.
If the data is valid, PCM_OP_CUST_CREATE_CUSTOMER calls the PCM_OP_ CUST_CREATE_ACCT opcode to create the /account object. PCM_OP_CUST_CREATE_ACCT 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:
Calls the PCM_OP_CUST_CREATE_BILLINFO opcode to create one or more /billinfo storable objects and propagates the bill unit with billing information. See "Creating /billinfo Objects" in BRM Configuring and Running Billing. Calls the PCM_OP_CUST_CREATE_BAL_GRP opcode to create one or more /balance_group storable objects and link the balance groups to the account and the appropriate /billinfo object. See "Creating Balance Groups" in BRM Managing Accounts Receivable. Calls the PCM_OP_CUST_CREATE_PAYINFO opcode to create a /payinfo object and link the payment information to the appropriate /billinfo object. See "Customizing Customer Payment Information".
Calls the PCM_OP_CUST_CREATE_PROFILE opcode to create a /profile object if the input flist contains profile information. See "Managing and Customizing Profiles". Calls the PCM_OP_CUST_SET_NAMEINFO opcode to set the contact information. See "Managing Customer Contact Information". Calls the PCM_OP_CUST_SETUP_TOPUP opcode to set up top-up information, if any, for the account. See "How BRM Sets up Top-Up Information for an Account" in BRM Configuring and Collecting Payments. Calls the PCM_OP_CUST_SET_STATUS opcode to set the account status to active. See "Setting Account, Service, and Bill Unit Status by Using Your Custom Application".
5.
PCM_OP_CUST_CREATE_CUSTOMER calls the PCM_OP_SUBSCRIPTION_ VALIDATE_DEAL_DEPENDENCY opcode to validate that the deals passed from the input flist do not violate any deal dependencies. PCM_OP_CUST_CREATE_CUSTOMER calls the PCM_OP_CUST_CREATE_ SERVICE opcode to create /service objects. See "Creating Services". PCM_OP_CUST_CREATE_CUSTOMER calls the PCM_OP_SUBSCRIPTION_ PURCHASE_DEAL opcode to purchase deals. See "Purchasing Deals". Before committing the transaction, PCM_OP_CUST_COMMIT_CUSTOMER calls the PCM_OP_CUST_POL_PRE_COMMIT policy opcode. See "Adding Custom Account Creation Steps before the Account is Committed". After committing the transaction, PCM_OP_CUST_COMMIT_CUSTOMER calls the PCM_OP_CUST_POL_POST_COMMIT policy opcode. See "Adding Custom Account Creation Steps after the Account is Committed".
6. 7. 8.
9.
10. PCM_OP_CUST_COMMIT_CUSTOMER:
Passes credit card information 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 multidatabase, and you do not use dblink, creates the /uniqueness object. Calls the PCM_OP_CUST_POL_GET_CONFIG policy opcode to get information used by client applications. Calls the PCM_OP_CUST_SET_BAL_GRP opcode to create balance groups. See "Creating Balance Groups" in BRM Managing Accounts Receivable.
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 Non-Currency Events" in BRM System Administrator's Guide.
1-5
For more information, see the description on JCA Resource Adapter transaction management in BRM JCA Resource Adapter.
Go to the BRM_Home/sys/data/config directory, where BRM_Home is the directory in which you installed the BRM software. Use the following command to create an editable XML file of the subscription instance from the /config/business_params object:
pin_bus_params -r -c "Subscription" bus_params_subscription.xml
This command creates the XML file named bus_params_subscription.xml.out in your working directory. To place this file in a different directory, specify the full path as part of the file name.
3.
4.
5. 6.
Save this updated file as bus_params_subscription.xml. Use the following command to load this change into the /config/business_params object in the BRM database. pin_bus_params bus_params_subscription.xml You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see the description for pin_bus_params in the BRM System Administrators Guide.
7.
Read the object with the testnap utility or Object Browser to verify that all fields are correct. For more information on reading objects by using the Object Browser, see BRM Managing Customers. For instructions on using the testnap utility, see BRM Developers Guide.
8. 9.
Stop and restart CM. See "Starting and Stopping the BRM system" in BRM System Administrator's Guide. For multiple databases, run the pin_multidb script with the -R CONFIG parameter. For more information on this script, see pin_multidb in BRM System Administrator's Guide.
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 configuration file (pin.conf) is used.
BRM does not allow backdating the account creation to a date prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date".
Immediately charges the cycle forward fee for the period of September 1 to October 1. The bill for October 1 contains a monthly cycle fee charge of $19.90 ($9.95 for the period of September 1 to October 1 and $9.95 for the period of October 1 to November 1). The bill for November 1 contains a monthly cycle fee charge of $9.95 for the period of November 1 to December 1.
When you backdate the creation of an account that has cycle arrears events, cycle arrears fees are not generated at the time of account creation. The backdated cycles are charged during the skipped billing that gets triggered for these cycles as a result of the next bill run. For example, consider that a customer places a request for an account creation on September 1, but the entry is recorded in BRM system on November 1. So, on November 1, the entry is backdated to September 1. The account owns a product with cycle arrears charges of $9.95 and the proration set to Charge based on amount used. BRM calculates the cycle arrears fee as follows:
About Registering Customers 1-7
The bill for October 1 contains a monthly cycle fee charge of $9.95 for the period of September 1 to October 1. The bill for November 1 contains a monthly cycle fee charge of $9.95 for the period of October 1 to November 1.
Important:
BRM does not prevent backdated creation, modification, or deletion of the discount sharing group and charge sharing group. However, the resource sharing is not effective from the backdated date. For example, on October 1, the group owner of a discount sharing group is modified and backdated to January 1 to include a group member account. The group member cannot enjoy discounts owned by the group owner with effect from January 1. For discounts to be effective from January 1, you must run rerating on all the accounts in the sharing group. BRM does not support backdating the change of the billing DOM. For example, you change the DOM from 5 of every month to 1 of every month. You cannot backdate this change to an earlier date.
Modifying an Account
To modify an account, use the 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 Bills Payment Method". Bill units Top-up information Balance groups Profiles Locale
PCM_OP_CUST_MODIFY_CUSTOMER adds a service by adding a deal to the account. PCM_OP_CUST_MODIFY_CUSTOMER adds a deal by calling standard opcodes to perform these operations:
If the validate_deal_dependencies entry is enabled in the Connection Manager pin.conf file, PCM_OP_CUST_MODIFY_CUSTOMER verifies that any set deal dependencies are valid. If not, the operation is disallowed. See "Defining Deal Dependencies". Purchase the deal associated with the plan. See "Purchasing Deals".
Set the account credit limit for each resource of the added plan. See "How BRM Handles Consumption Rules and Credit Limits". Create service objects associated with the plan. If a service with an add-on plan 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 plan 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 plan-to-discount exclusion rules at purchase time.
If a subscription service is being added, PCM_OP_CUST_MODIFY_ CUSTOMER verifies that it is not a member of another subscription 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 services balance group.
Optionally associate /device objects with the services. See "Managing Devices With BRM" in BRM Developer's Guide. Create notification events to mark the beginning and end of its execution. See "About Event Notification" in BRM Developer's Guide.
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 includes a hook to the PCM_OP_CUST_ POL_POST_MODIFY_CUSTOMER policy opcode, which you can use to export customer data to an external or legacy system for processing. See "Customizing registration". Table 11 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 11 Opcodes and Information Received to Create or Modify Objects Uses Information from This Array PIN_FLD_NAMEINFO PIN_FLD_PHONES (subarray) PCM_OP_CUST_SET_BAL_GRP PIN_FLD_ACCTINFO PIN_FLD_BAL_INFO (subarray) PCM_OP_CUST_SET_BILLINFO PIN_FLD_BILLINFO /billinfo /balance_group To Create or Modify This Object /account
1-9
Table 11 (Cont.) Opcodes and Information Received to Create or Modify Objects This Opcode PCM_OP_CUST_SET_PAYINFO Uses Information from This Array PIN_FLD_PAYINFO PIN_FLD_CC_INFO (subarray) PIN_FLD_DD_INFO (subarray) PIN_FLD_INV_INFO (subarray) PCM_OP_SUBSCRIPTION_SERVICE_ BALGRP_TRANSFER PIN_FLD_ACCTINFO PIN_FLD_BAL_INFO (subarray) PIN_FLD_BILLINFO PCM_OP_CUST_SET_LOCALE PCM_OP_CUST_CREATE_PROFILE PCM_OP_CUST_MODIFY_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 PIN_FLD_LOCALE PIN_FLD_PROFILES /account /profile /balance_group /billinfo To Create or Modify This Object /payinfo/cc /payinfo/dd /payinfo/invoice
If the information is successfully updated, the opcode returns the Portal object ID (POID) of the /event storable 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 /account.
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 PIN_FLD_ACCOUNT_OBJ POID 0 PIN_FLD_PROGRAM_NAME STR 0 PIN_FLD_BILLINFO ARRAY 1 PIN_FLD_BILLINFO_ID STR 1 PIN_FLD_PAY_TYPE ENUM 1 PIN_FLD_BILLING_SEGMENT ENUM 1 PIN_FLD_PAYINFO_OBJ POID ... [0] 0.0.0.1 /account 23304551863 227 [0] 0.0.0.1 /account 23304551863 227 [0] "program_name" [0] allocated 20, used 3 [0] "Account Bill" [0] 10005 [0] 0 [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 /billinfo object 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 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 above example, the new /payinfo object is created and associated with the /billinfo object 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, use PCM_OP_CUST_CREATE_SERVICE. If the PIN_FLD_SUBSCRIPTION_OBJ field in the input flist specifies the POID of a subscriptions service object, the service being added to the customers account will be a member of the subscription services group. The PCM_OP_CUST_CREATE_SERVICE opcode creates the service by doing the following inside a transaction:
Calls the PCM_OP_CUST_INIT_SERVICE opcode to create and initialize the /service object. Calls the PCM_OP_CUST_SET_PASSWD opcode 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". Stores any client-supplied inherited information in the /service object. See "Creating Customization Interfaces" in BRM Developer's Guide. Calls the PCM_OP_CUST_SET_STATUS opcode to set the service status. See "Setting Account, Service, and Bill Unit Status by Using Your Custom Application". Calls the PCM_OP_DEVICE_ASSOCIATE opcode to associate /device objects with the service. See "Managing Devices With BRM" in BRM Developer's Guide.
Modifying Services
To modify a service, use the PCM_OP_CUST_UPDATE_SERVICES opcode. For most services, this wrapper opcode calls the PCM_OP_CUST_MODIFY_SERVICE opcode 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. 2. 3. 4. 5. 6.
Creates an /event/notification/service/pre_change event. If login or alias list information is specified, calls the PCM_OP_CUST_SET_LOGIN opcode to update the service login or alias list with the value specified. If password information is specified, calls the PCM_OP_CUST_SET_PASSWD opcode to update the service password with the value specified. If service status information is specified, calls the PCM_OP_CUST_SET_STATUS opcode to update the status of the service with the value specified. If inherited fields are specified, calls PCM_OP_CUST_MODIFY_SERVICE for most services to update the values for the inherited fields. If one or more PIN_FLD_DEVICES arrays are specified, calls the PCM_OP_ DEVICE_ASSOCIATE opcode to disassociate or associate the device. Disassociations are processed before associations. Creates an /event/notification/service/post_change event.
7.
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 12:
Indexes and Input Flist Values in PIN_FLD_RESULTS Input Flist Value Login Password Status Inherited information
Table 12
Index Value 0 1 2 3
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, PCM_OP_CUST_MODIFY_SERVICE 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 input flist for PCM_OP_CUST_MODIFY_SERVICE 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.
Deleting Accounts
Caution:
2
2
This chapter provides an overview of Oracle Communications Billing and Revenue Management (BRM) customer management.
Caution: Do not use or modify this product except as explicitly instructed in this documentation. Assumptions should not be made about functionality that is not documented or use of functionality in a manner that is not documented. Use or modification of this software product in any manner or for any purpose other than as expressly set forth in this documentation may result in voidance or forfeiture of your warranties and support services rights. Please consult your software license agreement for more details. If you have any questions regarding an intended use or modification of this product, please contact Oracle.
See "Typical Customer Management Tasks" for information about customer management procedures.
About Accounts
Each of your customers has an account in the BRM database. BRM accounts include or are linked to information about the customers name and address, product and services, and the current balance. In addition to customer accounts, the database includes the following special-purpose accounts:
The root account is used by system administrators to set permissions for customer service representatives (CSRs).
Note:
BRM excludes the root account from billing. Therefore, BRM does not permit the root account to purchase services, deals, or plans for itself.
CSR accounts allow CSRs to log in to the BRM system. You also use CSR accounts to track CSR activity. See "Setting up Permissions in BRM Applications" in BRM System Administrator's Guide. Remittance accounts are used to track commissions for business-to-business relationships. See "Remitting Funds to Third Parties" in BRM Configuring and Running Billing.
2-1
The verification account is used to track customer login failures. See "Tracking Customer Authentication and Authorization Records".
An account can also have multiple balance groups. Each balance group keeps track of how much a customer owes or is owed for one or more specific services. This means an account can own two services of the same type and each service can have its own credit limit. For more information about how resources are tracked and updated in account sub-balances, see About tracking resources in account sub-balances.
Text entered in the Comments box of the Account Creation or Purchase wizard is not saved as a note. Instead, it appears in the Comments box in an accounts Product Detail panel.
2-3
See "Creating General Account Notes" for more information. To review general notes, see "Displaying Notes in Customer Center".
When you enter text in a Notes box and save your changes, Customer Center creates a note and saves it in an action-specific category. The category is identified when the note is displayed in the Notes dialog box as shown below in Figure 23:
The category in which a note is saved depends on the action performed. For example, if the action illustrated above was a debit instead of a credit, it would be categorized as A/R Debit Account. To review notes about specific actions, see "Displaying Notes in Customer Center".
Note:
Text entered in the Comments box of the Account Creation or Purchase wizard is not saved as a note. Instead, it appears in the Comments box in an accounts Product Detail panel.
Text entered in the Comments box of the Account Creation or Purchase wizard is not saved as a note. Instead, it appears in the Comments box in an accounts Product Detail panel.
To display all notes created for an account in Customer Center, see the discussion on displaying notes in BRM Customer Center Online Help.
Reasons for changing an account are stored in the BRM database. You can edit the list of reasons for the following changes:
About Managing Customers 2-5
Activating or inactivating an account Closing an account Crediting, debiting, or adjusting an account Charging an account Changing credit limits
Customer Center displays the reasons on lists. You can add, edit, or delete the text for these reasons by modifying the reason objects stored in the BRM database. To modify the reasons file, you edit the reasons.en_US sample file in the BRM_ Home/sys/msgs/reasoncodes directory, where BRM_Home is the directory in which you installed the BRM software. You then use the load_localized_strings utility to load the contents of the file into the /strings objects. See "load_localized_strings" in BRM Developer's Guide. When you run the load_localized_strings utility, use this command:
load_localized_strings reasons.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see Locale names. If you add your own reason codes to the reasons.locale file, you should use IDs above 100,000.
Caution: The load_localized_strings utility overwrites existing /config/map_glid and /config/reason_code_scope objects. If you are updating these objects, you cannot load new General Ledger (G/L) ID maps and reason code scopes only. You must load complete sets of data each time you run the load_localized_strings utility. This is also true when using the /strings object, but only if you specify the -f parameter. Otherwise, the load_localized_strings utility appends the new data to the object.
For information on loading the reasons.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide. See "Creating New Strings and Customizing Existing Strings" in the same document for information on creating new strings for this file.
Customizing Search
You can customize Customer Center search functions.
Cannot log in to a service. Common reasons customers cannot access their accounts are: They typed the wrong login name or password. They forgot that passwords are case sensitive. The account is inactive or closed. There are credit problems.
Possible ways to address the problem are: Check the login name. See "Managing Customer Authentication".
2-7
Check the status of the account. See "Changing Account and Service Status". Check the credit card number and expiration date. See "Changing Credit Card Information". Check the credit limit. See "Changing a Customers Credit Limit". Check the amount due.
Wrong amount on a bill. Common complaints are: I was not told I would be charged for this. My bill is being sent to the wrong address. I did not order this.
Cancel the service. See "Managing Services". Change the billing address. See "Managing Customer Contact Information". Make an adjustment. See "About adjustments" in BRM Managing Accounts Receivable. Open a dispute. See "About Opening and Resolving Disputes" in BRM Managing Accounts Receivable.
Change an address or phone number. Change an email address, password, or login name. Add or cancel services. Find out the current balance.
CSRs need to be able to tell your customers the following information about plans and deals: Which services are included in each plan. The sign-up fee, monthly fees, and usage fees. Discounts, and when they apply. What happens when the plan is canceled; for example, is there a cancellation fee, and are fees paid in advance prorated and reimbursed. Expiration dates.
If CSRs can change service properties, they need to know what changes they are allowed to make; for example, if they can enter blocked numbers for a telephony service. CSRs need to know which information is required for registration. They also need to know the valid formats for entering information; for example, how to enter a telephone number, salutation, or title. (For more information, see "Standard
Customers often have questions about changes to their account status. CSRs should know the reasons why an account can be inactivated and what needs to be done to activate an inactive account.
You can also log CSR activities if you have included them in the pin_notify file. For more information, see "Logging Customer Service Representative Activities" in BRM System Administrator's Guide.
Accessing Audit Trail Information for instructions on accessing audit trail information from the BRM database About Tracking Changes to Object Fields for information on how audit trails work Enabling Auditing for a Field for instructions on making new and existing object fields auditable.
2-9
Centralized installation: You deploy Customer Center from a central Web server, making it available to each CSR to download and use locally. Each time a CSR starts Customer Center, the application checks the server and downloads any updates, using Suns Java Web Start technology. Customization: You can add new panels to the Customer Center interface, make certain modifications to existing panels, and customize other aspects of Customer Center by using the Customer Center SDK.
Note:
Rename or remove fields. Change its basic look and feel. Add functionality, such as entirely new fields or custom services. This type of customization requires programming.
For more information, see Customizing the Customer Center interface in BRM Developer's Guide.
You can manage CSRs access to Customer Center data and functionality. For more information, see "Setting up Permissions in BRM Applications" in BRM System Administrator's Guide.
Summary Tab
By default, this tab is active when you first open an account. This tab gives you an overview of the open account, including:
Name, address, and other contact information for the account holder. Account summary, including the status, creation date, number of deferred actions, customer type, security codes, and if the account was created by the user. Current balance. Credit limit. Number of unresolved disputes. Payment method.
You can take the following actions by clicking links on the Summary tab:
Change the account holders information or create more contacts for the account. Change the status of either the account or any service the account owns. Display self-registration information, such as promotional codes, if your customer created the account on the Web. Change the accounts credit limit. Resolve a dispute. Change the accounts payment method.
Balance Tab
This tab displays an overview of the accounts balance and bills, including:
Current balance for the account and for the bill in progress, or the bill for the current billing cycle. Credit limit. Summary of non-currency resources, if the account uses any. List of the accounts bills including the payment received for each bill.
You can also do the following from this tab, by clicking links and using commands:
Adjust the account; for example, to give the customer credit for a service problem. Allocate adjustments or payments. Display the bill in progress. Change the accounts credit limit. Resolve a dispute. View details of a bill. View the invoice for a selected bill. View A/R actions: adjustments, write-offs, and disputes, for all bills. Search for and adjust events associated with a selected bill. Write off a bill or an item. Adjust an item for a selected bill. Adjust an event. Open and settle a dispute. Refund a bill.
Payments Tab
This tab displays:
List of payments the account has made and how much of each payment has been allocated. Payment setup information, which is different for each payment method. Tax setup information.
You can also do the following from this tab, by clicking links and using commands:
View more details about a payment. Search for and display payments for different time periods. Allocate an unallocated payment. Export the current list of payments to an HTML page. Change billing information, including the payment method, name and address, and credit card number. Add, delete, or change a tax exemption. Export a list of payments to an HTML file.
Product Tab
This tab displays each product that the account owns and basic information about each product, including the products service, purchase date, and status. You can click a product name to see more details, such as the product quantity, discounts, and fees, and to customize the product. You can also do the following from this tab:
Purchase new products. Cancel a deal or product. Customize the display of products on this tab. Review the history of a product, deal, or service.
Service Tab
This tab displays the services that the account owns. For each service, it lists the login name or ID, status, and number of deferred actions. Some services may be subscription services or member services. You can click a services status to change it. You can change the status of a member service without affecting the other members of a subscription group. If you change the status of a subscription service, the status of its member services changes accordingly. You can also change the login name or ID for a service and the password, if one is required.
Note:
For some BRM services, additional fields appear below New Password.
View Alias You can view the available alias or aliases for telco services. An alias is an additional identity associated with a service. For example, a Service ID can have aliases such as International Mobile Subscriber Identity (IMSI) and Mobile Subscriber Integrated Services Digital Network Number (MSISDN) associated with it. You use View Alias from the Actions menu to view the available alias or aliases for the selected telco service.
Note:
View Aliases is available only if the selected service is a telco service. If no aliases are available, the dialog box displays a message to that effect.
Hierarchy Tab
For the parent account or member of an account hierarchy, you can see the accounts belonging to the hierarchy. You can also do the following from this tab:
Move any account into a hierarchy. Move an account from one hierarchy to another. Move an account to a different position within the same hierarchy. Remove a child account from a hierarchy. Open any account in the hierarchy.
Sponsorship Tab
In this tab, you can see if an account owns a sponsor group or if it is sponsored by another account. For an account that owns a sponsor group, this tab displays:
A list of groups that the account sponsors. Products and rate plans for each sponsor group. Members of each sponsor group.
For a group owner, you can do the following from this tab:
Create and delete sponsor groups. Add or remove rate plans. Add or delete group members. Open any members account.
For an account that belongs to a sponsor group, you can display a list of sponsor groups and rate plans that the account belongs to. From that list, you can also display the account of the sponsor groups owner. For any account, you can create a new sponsor group from this tab.
Summarize the impacts of events on the resource balances in an account. For example, you can see how login events during one month affected the balance of dollars and hours in a customers account. Cancel the effects of events on resource balances. For example, if a customer was charged the wrong amount, you can cancel the charge by adjusting the event that generated the charge. Review detailed information about a customers account such as credits, debits, dialup sessions, and name changes.
About Managing Customers 2-13
You access Event Browser from Customer Center. For more information, see "Using the Event Browser to Display and Adjust Events" in BRM Managing Accounts Receivable.
ADU can be performance intensive, depending on the number of accounts for which data is being retrieved and the volume of data being processed. Avoid running performance-intensive operations, such as billing, while running ADU.
Create an input file with the account search specification. ADU uses the specification to select accounts in the BRM database. See "About ADU Account Search". ADU searches the accounts in the BRM database, retrieves the related object information, and dumps the information to an output file. See "About ADU Account Dump". ADU validates the contents of the output file. See "About Account Data Validation".
2.
3.
The following search flist requests the dump of all the accounts with billing day of month (DOM) as 1:
0 0 0 0 1 0 1 PIN_FLD_POID POID [0] 0.0.0.1 /search/pin -1 0 PIN_FLD_FLAGS INT [0] 256 PIN_FLD_TEMPLATE STR [0] "select X from /billinfo where F1 = V1 " PIN_FLD_RESULTS ARRAY [0] PIN_FLD_ACCOUNT_OBJ POID [0] NULL PIN_FLD_ARGS ARRAY [1] PIN_FLD_ACTG_CYCLE_DOM INT [0] 1
Note:
ADU considers each account as a standalone. If a group owner account is specified in the search flist, ADU dumps only the contents of the owner account. ADU will not dump the contents of the group member accounts. Similarly, if a group member account is specified in the search flist, only the contents of the member account is dumped. ADU will not dump the contents of the owner account or other group member accounts. The PIN_FLD_RESULTS array in the search flist must contain only PIN_FLD_ACCOUNT_OBJ.
Important:
ADU can be performance intensive, depending on the number of accounts for which data is being retrieved and the volume of data being processed. Run ADU in -report mode first to determine the volume of data to be processed so that you can optimize your account search for best performance. See "pin_adu_validate" in BRM Developer's Guide.
By default, ADU dumps the object contents in the output file in XML format. If you prefer a different output format (for example, CSV), you can customize the output format by modifying the PCM_OP_ADU_POL_DUMP policy opcode. See BRM Developer's Reference.
These objects normally contain large volumes of data. To limit the amount of data retrieved from these objects, you can use the date range option to select only data that was updated between a specified period. For example, if you choose to dump the contents for /account, /service, /bill, and /item and specify the date range to be between February 1, 2007 (dump_start_time) and March 1, 2007 (dump_end_time), ADU uses the date range for searching and retrieving data from the /bill and /item objects only. The date range is not used for retrieving data from the /account and /service objects. The date range is mapped to the object date fields as follows:
For the /audit object, ADU selects only those objects whose created_t or effective_t is between dump_start_time and dump_end_time. For the /bill object, ADU selects only those objects whose end_t is between dump_ start_time and dump_end_time. For the /item object, ADU selects only those objects whose effective_t is between dump_start_time and dump_end_time. For the /event object, ADU selects only those objects whose end_t is between dump_start_time and dump_end_time. For the /invoice object, ADU selects only those objects whose created_t is between dump_start_time and dump_end_time. For the /balance_group object, ADU selects only those objects whose effective_t is between dump_start_time and dump_end_time.
Predefined Structural and Dynamic Validations Validation code struct_ valid_01 struct_ valid_02 Description Validates that /event objects point to the correct /item objects based on the mappings configured in /config/item_tags and /config/item_types. Validates that the PIN_FLD_PARENT field of the subordinate accounts last bill points to the parent /bill object. Validates that the bill number of the subordinate account and the bill number of the parent account are the same.
Structural
Validates that the DOM of the subordinate account and the DOM of the parent account are the same. Validates that the AR_BILLINFO_OBJ of the subordinate account points to the /billinfo object of the parent account. Validates that the /item due amount is zero after payment.
You enable these validations by setting the corresponding validation code in the ADU pin.conf file. ADU logs the results of the validations in the Connection Manager (CM) log file. You can customize additional validations by modifying the PCM_OP_ADU_POL_ VALIDATE policy opcode.
Configuring ADU
To configure ADU, set the entries in the ADU configuration file (BRM_ Home/sys/diagnostics/pin_adu_validate/pin.conf) shown below in Table 22:
Table 22 Entry - pin_adu input_file filename Entries in the ADU Configuration File Description Set filename to the name of the input file that contains the account search specification. For example: - pin_adu input_file opt/portal/7.5/sys/diagnostics/pin_ adu_validate/in/input.txt - pin_adu output_file filename Set filename to the name of the output folder where ADU should write the output file. For example: - pin_adu output_file /opt/portal/7.5/sys/diagnostics/pin_adu_validate/out - pin_adu out_file_ext.ext Set ext to the output file extension. For example: - pin_adu out_file_ext.xml - pin_adu obj_list object1; [object2]; ... Specify the objects to dump for the selected accounts. For example: To dump /billinfo and /payinfo objects: - pin_adu obj_list /billinfo; /payinfo Note: Use a semicolon to separate items in the object list.
Table 22 (Cont.) Entries in the ADU Configuration File Entry - pin_adu obj_flds object1:field1, field2,... [object2:field1, field2,...] ... Description Specify the fields in the objects to dump. For example: To dump the first and last name of an account: - pin_adu obj_flds /account: PIN_FLD_ NAMEINFO.PIN_FLD_FIRST_NAME, PIN_FLD_ NAMEINFO.PIN_FLD_LAST_NAME To dump account invoice information: - pin_adu obj_flds /payinfo/invoice: PIN_FLD_INV_ INFO Note: Use a colon to separate the items in the object list. - pin_adu dump_start_time time - pin_adu dump_end_time time Set time in these entries to the times to be used for selecting most commonly updated objects. - pin_adu dump_start_time 1175385600 - pin_adu dump_end_time 1177977600 Note: time must be in UTC format. - pin_adu struct_valid_01 n - pin_adu struct_valid_02 n - pin_adu struct_valid_03 n - pin_adu struct_valid_04 n - pin_adu dynamic_valid_01 n - pin_mta logfile filename Set filename to the ADU log file. All the debug and error messages generated by ADU will be logged to this file. - pin_mta logfile /opt/portal/7.5/sys/diagnostics/pin_ adu_validate/adu.pinlog - pin_mta loglevel n Set n to the level of information to log in the ADU log file. Log level values are: 0: no logging. 1: log error messages only. 2: log error messages and warnings only. 3: log error messages, warnings, and debug messages. - pin_mta loglevel 2 Use these entries to enable (1) or disable (0) the predefined validations. For example: - pin_adu struct_valid_01 1 - pin_adu dynamic_valid_01 1
3
3
Customizing Registration
This chapter describes Oracle Communications Billing and Revenue Management (BRM) customer registration options that are common to customer service representative (CSR)-based and Web-based registration. Before reading this document, see "About Registering Customers".
The plan that the customer signs up for. Contact information; for example, name, address, and telephone number. Service login and Web access names and passwords. Customers language. See "Charging Customers at Registration". Customers account currency. Billing information; for example: The accounting type (balance forward or open item). The frequency of the billing cycle. The payment method (credit card, invoice, and so forth). Payment information; for example, credit card number or invoice billing address.
The information required by default is the last name, address, city, and country. You can change the required fields by using the Field Validation Editor, a Configuration Center application. If you require additional registration information, you can create custom fields. See "Creating New Registration Fields".
You can send localized versions of invoices to customers based on their language. Your Internet Protocol (IP) telephony gateway can play voice messages in the customers language.
You should tell your CSRs what the valid formats are. To see the default validation formats, see the Field Validation Editor in Configuration Center.
Tax calculation programs validate ZIP codes. If you use a tax calculation package other than Taxware, make sure that your tax calculation program can handle 9-digit ZIP codes.
Name information Billing information Payment information Locale information Service login and password information Profile information
Each array has a flag to specify whether to validate partial information for that array. If the flag is set, PCM_OP_CUST_VALIDATE_CUSTOMER performs a partial validation. If the flag is not set, the opcode performs a complete validation. If you provide a field that is dependent on another field for validation, you need to provide both the fields. For example, if the state, ZIP code, or phone field is provided for validation, then you must also provide the country field. If there are no errors, PCM_OP_CUST_VALIDATE_CUSTOMER returns the results array in the output flist. If there are errors, it returns an flist with the first field that was not updated.
Important:
You need to explicitly delete the return flist after using it, by calling the PIN_FLIST_DESTROY routine.
Specifying the Account that Records Credit Card Validations Allowing Registration without a Credit Card Validating Credit Cards at Registration Allowing Registration without Credit Card Validation
Open the Connection Manager (CM) configuration file (BRM_ Home/sys/cm/pin.conf). BRM_Home is the directory in which you installed the BRM software. Change the account number in the following entry:
- fm_pymt_pol validate_acct database_number /account 1
2.
where (database_number is the database number of the BRM database; by default, this is 0.0.0.1).
3.
You do not need to restart the CM to enable this entry. To customize this feature, use the PCM_OP_PYMT_POL_SPEC_VALIDATE policy opcode. See "Customizing the Account Used for Credit Card Validation".
The credit card transaction processing service is unavailable. The ZIP code is valid but the street address is wrong.
The wrong ZIP code was entered. The credit card is not valid. The address was not entered or could not be read by the credit card processor.
1. 2.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the cc_validate entry:
To enable credit card validation, enter 1. To disable credit card validation, enter 0.
3.
Important:
The PCM_OP_CUST_COMMIT_CUSTOMER opcode first calls the PCM_OP_PYMT_VALIDATE opcode to validate credit cards. If validation is successful, the customer account is created. Then, PCM_OP_CUST_COMMIT_CUSTOMER calls the PCM_OP_ PYMT_COLLECT opcode to charge the credit card. If the authorization for funds fails, the account will not be charged.
If you use Paymentech, edit the Paymentech DM configuration file. See "Increasing Registration Speed When Paymentech is Offline" in BRM Configuring and Collecting Payments. Modify the PCM_OP_PYMT_POL_VALIDATE policy opcode to map the no answer result to success, so that the registration continues.
Tip: If the credit card payment service is not available and you still want to register customers, you need to isolate those accounts for later credit card authorization. Modify the PCM_OP_PYMT_POL_ VALIDATE policy opcode file either to save a list of permissive registrations or to send email to the system administrator. Alternatively, you can write a simple application to periodically check accounts and flag the ones that have been registered without verification.
1. 2. 3.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the cc_revalidation_interval entry. The default is 3600 seconds (one hour). Save the file.
Amount due for all bills: 0 Adjustments/Payments not applied: 0 Due now: 0
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the -fm_pymt_pol cc_collect entry:
To enable credit card collection, enter 1. To disable credit card collection, enter 0.
3.
You do not need to restart the CM to enable this entry. To customize this feature, use the PCM_OP_PYMT_POL_SPEC_COLLECT policy opcode. See "Customizing whether to Charge at Registration".
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.
The PCM_OP_PYMT_POL_SPEC_COLLECT policy opcode then calls the PCM_OP_ PYMT_GET_ACH_INFO opcode 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 the PCM_OP_PYMT_POL_SPEC_COLLECT policy opcode 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). See "Charging Customers at Registration".
Specifying the Default Account Currency Specifying the Default Country Changing the Account Number Format Defining Customer Email Domain Names Specifying the Valid Expiration-Date Format
1. 2.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Enter a currency code in the currency entry. For a list of currency codes, see BRM_Home/include/pin_currency.h.
3.
The new value becomes effective immediately and applies to the next account created. You do not need to restart the CM to enable this entry.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the country entry:
fm_cust_pol country USA
Note:
The country name must conform to the validation rules for country names set in the Field Validation Editor. See "Specifying how to validate customer contact information".
3.
The new value becomes effective immediately and applies to the next account created. You do not need to restart the CM to enable this entry.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the domain entry.
fm_cust_pol domain isp.nz
3.
The new value becomes effective immediately and applies to the next account created. You do not need to restart the CM to enable this entry.
Go to BRM_Home/sys/data/config, which includes the support files used by the pin_bus_params utility. Use the following command to create an editable XML file from the business_ params_subscription instance of the /config/business_params object:
pin_bus_params -r BusParamsSubscription bus_params_subscription.xml
This command creates the XML file named bus_params_subscription.xml.out in your working directory. If you do not want this file in your working directory, specify the path as part of the file name
3.
4.
BRM uses the XML in this file to overwrite the existing subscription instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM subscription configurations.
5. 6.
Save the file as bus_params_subscription.xml. Use the following command to load this updated file into the /config/business_ params object:
pin_bus_params bus_params_subscription.xml
7. 8.
Read the object with the testnap utility or Object Browser to verify that all fields are correct. Stop and restart the CM.
Use the CSR-new plan list to display plans when you create new accounts in Customer Center. Use the CSR-addon plan list to display plans when you add a service to an existing account in Customer Center. Use the default-new and default-addon plan lists when creating accounts or adding services by using Web-based registration. In most cases, you will use your own plan lists.
Note: The CSR plan lists override the default plan lists. If you have a CSR plan list and a default plan list, Customer Center displays only plans in the CSR plan list.
Plan and deal names and descriptions are displayed in Customer Center when creating an account and when adding services and deals.
While preventing customers from accidentally signing up for a duplicate account, you also run the risk of preventing customers who want two accounts from signing up for the second one.
Checking for duplicate registrations requires editing the source code of the customer validation policy opcodes. See "Customer FM Policy Opcodes" in BRM Developer's Reference.
PCM_OP_CUST_POL_PRE_COMMIT. See "Adding custom account creation steps before the account is committed". PCM_OP_CUST_POL_POST_COMMIT. See "Adding custom account creation steps after the account is committed". PCM_OP_CUST_POL_GET_CONFIG. See "Sending Account Information to Your Application when an Account is Created". PCM_OP_CUST_POL_POST_MODIFY_CUSTOMER. See "Sending Account Information to Your Application when an Account is Modified".
The PCM_OP_CUST_POL_POST_COMMIT policy opcode is called by PCM_OP_ CUST_CREATE_CUSTOMER just after the transaction containing the creation and initialization of the /account and /service storable objects has been committed. The PCM_OP_CUST_POL_POST_COMMIT policy opcode takes the entire registration flist as its input flist so any information about the customer can be used to interact with an external or legacy system. This policy opcode cannot alter the registration data used to create the customer. Because the transaction creating the customer storable objects has already been committed, this operation cannot prevent or alter the registration process in any way. If an ebuf error is returned by the PCM_OP_CUST_ POL_POST_COMMIT policy opcode, it is ignored by PCM_OP_CUST_CREATE_ CUSTOMER. No information is returned as output parameters.
The POP_TOLL_FREE flag, if set, indicates whether the POP will be 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:
The default implementation uses /pop storable objects in the database to determine the POP information to return. Applications are provided with BRM to load POP storable 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.
Customizing Registration 3-15
To get a list of databases, use the PCM_OP_CUST_POL_GET_DB_LIST policy opcode. See "Getting a List of Databases". To select a database, use the PCM_OP_CUST_POL_GET_DB_NO policy opcode. See "Selecting a Database".
Selecting a Database
In a multidatabase system, the criteria for selecting a database is set in the BRM_ Home/setup/scripts/pin_multidb.conf file. See Setting database priorities. During account creation, PCM_OP_CUST_COMMIT_CUSTOMER calls the PCM_OP_CUST_ POL_GET_DB_LIST policy opcode to select a database for the new account. You can customize the selection process by customizing the PCM_OP_CUST_POL_ GET_DB_NO policy opcode. If you are not using the multidatabase feature, this step is ignored at account creation.
4
4
For information about Web registration and account access, see "Ways to Implement a Web Interface". To add or change Self-Care Manager functionality, see "Customizing the Self-Care Manager Interface" in BRM Developer's Guide.
A set of Java Server Pages (JSPs) that display HTML forms in a standard Web browser. The JSPs can display data, such as a list of available plans, from the BRM database. You can customize the JSPs to change the appearance of the Web pages or to change the data that you receive from or display to customers. For more information about JSPs, see Sun Microsystems Java documentation.
A set of BRM Business Application SDK (BAS) beans that provides an interface between the JSPs and BRM. The BAS beans connect to a Connection Manager (CM) and transfer data to and from BRM. A programmer can create custom controllers and other Java components to customize the data that you display or receive from customers. For more information, see "Customizing the Self-Care Manager Interface" in BRM Developer's Guide.
An application server that processes requests originating from customer Web browsers, manages customer sessions, and transfers data to and from the BAS beans. For more information, see the JavaSoft documentation.
The JSPs and the application server are run by your Web server.
4-1
You can change the appearance of Self-Care Manager pages by editing the HTML files, JSPs, and style sheet. This requires HTML knowledge. See "Changing Web pages" for more information. You can modify or add source code to collect additional information from your customers or to provide your customers with additional options. This requires the Customer Center SDK as well as Java programming knowledge.
About Currencies
All accounts created in Self-Care Manager use the default account currency for your BRM system. Your customers do not have the option of selecting a currency when they register through Self-Care Manager. You can change the default currency Self-Care Manager uses by changing the default account currency. See "Setting the Default Account Currency". If you want customers to have the option of selecting a currency, a programmer can customize Self-Care Manager to add a currency field. See "Customizing the Self-Care Manager Interface" in BRM Developer's Guide.
The application server and Self-Care Manager must be installed on the same system.
Note:
The Connection Manager (CM) need not be on the same system as Self-Care Manager.
See "Installing Self-Care Manager on Windows" in BRM Developer's Guide or "Installing Self-Care Manager".
Apache Tomcat. See "Setting up Apache Tomcat". WebLogic. See "Setting Up Oracle WebLogic". WebSphere. See "Setting Up IBM WebSphere".
Requirements
Your Self-Care Manager WAR file. See "Customizing the Self-Care Manager Interface" in BRM Developer's Guide. The directory in which Self-Care Manager is installed. The default is BRM_ Home/WebKit/WebKit, where BRM_Home is the directory in which you installed the BRM software.
Install Apache Tomcat. For information, see the Apache Tomcat documentation. Deploy your WAR file as a new Web component by using the Apache Tomcat interface. Copy the WebKit.properties and Infranet.properties files from BRM_ Home/WebKit/WebKit to Tomcat_home\lib. Stop and restart the Tomcat server. Your Self-Care Manager application is now deployed.
Requirements
Creating a new WebLogic domain. Your Self-Care Manager WAR file. See "Customizing the Self-Care Manager Interface" in BRM Developer's Guide. The default directory in which Self-Care Manager is installed. The default is C:\Program Files\Portal Software\Self Care Manager.
4-3
Install WebLogic. For information, see the WebLogic documentation. Create WebLogic domain. For information, see the WebLogic documentation. Copy the WebKit.properties and Infranet.properties files from C:\Program Files\Portal Software\Self Care Manager to WebLogic_ home\mydomain\applications\webkit_en\WEB-INF\classes. Start the WebLogic server. Deploy your WAR file as a new Web component by using the WebLogic interface. For information, see the WebLogic documentation. Stop and restart the WebLogic server. Your Self-Care Manager application is now deployed.
4. 5. 6.
Requirements
Your Self-Care Manager WAR file. See "Customizing the Self-Care Manager Interface" in BRM Developer's Guide. The default directory in which Self-Care Manager is installed. The default is BRM_ Home/WebKit/WebKit.
Install WebSphere. For information, see the WebSphere documentation. Deploy your WAR file by using the WebSphere application installation wizard.
Important:
Even though you have a Self-Care Manager WAR file, deploy your application within WebSphere as an Enterprise Application (*.ear) rather than as a WAR file. Install your WAR file as a standalone application.
3. 4.
When prompted for enterprise application information, select the defaults, then click Finish to complete the wizard. Copy the WebKit.properties and Infranet.properties files from BRM_ Home/WebKit/WebKit to Websphere_ home/AppServer/installedApps/myapplication. Stop and restart the WebSphere server. Your Self-Care Manager application is now deployed.
5.
Uninstall Self-Care Manager from your application server. See your application server documentation.
Note:
You may also have to remove from your application server any temporary directories created for Self-Care Manager.
2.
In Windows, choose Start - Programs - Portal - Uninstall Self-Care Manager and use the dialog box that appears.
This is the directory name for the English locale. Directory names for localized versions use the appropriate locale in place of en.
One approach to deploying Self-Care Manager so your subscribers can access it:
Configure your Web server to look for index.html as the default HTML home page. Have subscribers enter http://hostname/WebKit/htmlui_en in the Web browser.
Note:
If your Web server does not support specifying a default home page for each application, subscribers will need to enter the full URL, including the file name for the home page. For example, http://hostname/WebKit/htmlui_en/index.html.
Set up a separate application server for each locale. You set up multiple application servers with a single Web server. For information, see your application server documentation. You can then follow the standard procedure for configuring your application server for each combination of server and locale. For each server, deploy the WAR file for a different locale.
Set up a separate Web application in your application server for each locale.
4-5
Caution: If you use this method, you will encounter problems later if you try to use opcode and flist logging for troubleshooting.
For information on creating localized versions of Self-Care Manager, see "Localizing Self-Care Manager" in BRM Developer's Guide.
Open the Self-Care Manager properties file (SelfCareManager_install_ dir/WebKit.properties). Edit these entries:
user=root.0.0.0.1 password=password host=hostname port=11960
3. 4. 5.
Save and close the file. Open the Infranet.properties file (SelfCareManager_install_dir/Infranet.properties). Edit the infranet.connection entry; for example:
infranet.connection=pcp://root.0.0.0.1:password@host:40010/service/pcm_client 1
In this example:
The login name is root.0.0.0.1. The password is password. The hostname is host. The port is 40010.
6.
Save and close the file. To improve security, change the default root login name (root.0.0.0.1) and the default password (password). See "Configuring Login Names and Passwords for BRM Access" in BRM System Administrator's Guide.
Important:
Open the Self-Care Manager properties file (SelfCareManager_install_ dir/WebKit.properties). Enter the name of the plan list in the Infranet.PricingPlan entry; for example:
pricingplan=webclient
3.
Open the Self-Care Manager properties file (SelfCareManager_install_ dir/WebKit.properties). Change the singleLogin entry to:
singleLogin=true
3.
infranet.bas.connectionpool.size: The maximum number of connections in the connection pool. More connections can improve performance but put a heavier load on the BRM server. Any value greater than 0 is valid. The default is 4.
infranet.bas.connectionpool.size = 4
Note:
If your BRM license limits the number of BRM connections you can have, consider this limit when specifying the number of connections that Self-Care Manager can use.
4-7
infranet.bas.connectionpool.timeout: The maximum time in milliseconds that customers wait for a BRM connection before getting notified that a connection is not available. If customers do not get a connection within this time, they get an error communicating with BRM message. You must add this parameter to the Self-Care Manager properties file (WebKit.properties) using a value appropriate for your installation. Any value greater than 0 is valid.
infranet.bas.connectionpool.timeout = connection_timeout_in_milliseconds
If you have multiple Self-Care Manager home pages, because your BRM system supports brands or for any other reason, you need to add those service types to each home page.
To add a service:
1. 2.
Open the Self-Care Manager home page with an HTML editor or text editor. The default Self-Care Manager home page is index.html. Locate this section of the file:
<SELECT Name="service" Size="1"> <OPTION Value="ip" SELECTED>ip <OPTION Value="email">email <OPTION Value="telephony">telephony </SELECT>
3.
For each service you want to appear on the list, add a new option to this list. For Value, enter the BRM name of the service. The name outside the OPTION tag is the name displayed on the Web page. For example:
<OPTION Value="gsm/sms">GSM SMS <OPTION Value="gsm/telephony">GSM Telephony <OPTION Value="gsm/data">GSM Data
4.
The error logs show an error communicating with Portal message The Web pages display errors Internet Explorer shows a page not found error
Brands are enabled in BRM, but you want some accounts created in Brand Host
The error logs show an error communicating with Portal message To debug this type of error, you turn on opcode and flist logging for the Java PCM. This logs the input and output flists for each opcode that Self-Care Manager calls. You can use these flists to see problems communicating with BRM. To turn on opcode and flist logging:
1. 2.
Open the Infranet.properties file in a text editor. The file is located in your Self-Care Manager installation directory. Add these lines to the file:
infranet.log.opcodes.enabled=true infranet.log.opcodes.file=pathname/opcodes.log
where pathname is the path to the directory for the log file. For example:
infranet.log.opcodes.file=d:/temp/opcodes.log
Important:
3. 4. 5.
Stop and restart the application server. Save and close the file. Reproduce the error and check the file applicationserver_install_ dir/servers/default/javaPCM.log.
The Web pages display errors The Web pages might display an error message or display Click to continue in place of the correct page. To debug this type of problem, you enable debugging in the error.jsp file so that exceptions are written to the log file debug_errorlog.jsp. This prints a stack trace, which can help developers locate where an exception occurred. To enable debugging in the error.jsp file:
1. 2.
Open the appropriate version of the error.jsp, located in the htmlui_en directory in the Self-Care Manager installation directory. Uncomment this line by removing <% and %>:
<%@ include file = "debug_errorlog.jsp" %>
3.
Internet Explorer shows a page not found error Internet Explorer masks the actual error by giving the error message page not found. You can turn off the error messages and see the actual error message by changing a setting in Internet Explorer: To disable Internet Explorer error messages:
1. 2. 3.
Choose Tools - Internet Options. Click the Advanced tab. Clear the Show friendly HTTP error messages check box.
4-9
Brands are enabled in BRM, but you want some accounts created in Brand Host If your BRM system has branding enabled but no brands have been created, or you want to have accounts that do not belong to a specific brand, you need to set up root as a brand: To set up root as a brand:
1. 2.
Open the Self-Care Manager properties file (SelfCareManager_install_ dir/WebKit.properties). Add the following line to the file:
brand.root=admin_client,root.0.0.0.1,password
3.
Logging In
Figure 42 shows the login page your customers see when they access your self-care Web site:
Finding or Searching for and Viewing Events Applying Voucher Top-Ups Viewing Resource Reservation Details Viewing Invoices Viewing Account Activity Viewing Products Purchased Paying Bills Online Viewing Service Details for a Bill Unit Viewing Bill Units in an Account Changing Login Name, Password, or Account Status
Based on the search criteria and the item types configured in WebKit.properties, events are retrieved and displayed in the Event Search page as shown in Figure 44.
Figure 44 Example Event Search
For example:
To view all the events related to cycle_forward, add /cycle_forward to the key EventSearch.ItemTypes in WebKit.properties:
EventSearch.ItemTypes=/cycle_forward
To view all the events related to adjustment and payment, add /adjustment and /payment to the key EventSearch.ItemTypes in WebKit.properties:
EventSearch.ItemTypes=/adjustment,/payment
then enter the voucher ID and pin and click Validate to check the resources and validity of the specified voucher. If the voucher is valid, the Apply button is enabled. If there are multiple balances in the bill unit, customers can select the balance groups whose account balance they want to top up. To apply the vouchers immediately and top-up the account balances, customers select the required balance groups, select Allocate Now and click Apply. See Figure 45. Customers can also choose to just apply the voucher on the balance groups and not top-up the account balance. To do this, the customer clicks Apply without selecting Allocate Now. The voucher can later be allocated, but only through Customer Center.
Figure 45 Voucher Top-Up Information for an Example Account
To view the reservation details, customers click the Reservations link and the details are displayed in the Resource Reservations Details page. If the credit limit of any of the balance groups is unlimited, the Credit Limit value is displayed as Unlimited as shown below in Figure 47.
Figure 47 Resource Reservation with Unlimited Credit Limit
To find the balance group, which has unlimited credit balance customers, click the Unlimited link displayed next to the Credit Limit. The Included Services page appears. See "Viewing Service Details for a Bill Unit".
Viewing Invoices
Customers can view their invoice details by generating a report of their past bills. To view the invoice details, customers click the Invoice link on the Account Information page. The Invoice Selection page appears as shown in Figure 48.
Figure 48 Selecting the Invoices to View
Customers can then select new start and end dates for the report or keep the default dates that represent the last billing cycle. After clicking Submit, the Invoice page appears, which lists invoices available for the selected period. In this page, customers click the invoice they want to view.
Customers can then select new start and end dates for the report or keep the default dates which represent the last billing cycle. After clicking Submit, the Account Activity page appears which shows the accounts details; for example, customers name, address, and event details in chronological order. If the customer uses additional services, some types of usage activity appear on separate pages. Links for the additional pages appear on the line just above the list of events.
If a discount was purchased as part of a deal, an icon appears before the deal name.
To pay the bill, customers enter an amount and credit card information and click Submit. BRM updates the customers balance the next time you run billing and collects the BRM-initiated payment. For more information, see "About Collecting BRM-Initiated Payments" in BRM Configuring and Collecting Payments. To view online bill payment records, customers click the Online Payment Audit link on the Online Payment page. A page appears on which they enter start and end dates. Self-Care Manager displays the payments made between the start and end dates.
Figure 413 Service Level Bill Unit Information for Selected Account
To view the details of a specific bill unit, click on the bill unit. The details are displayed in the Account Information page. For information, see "Accessing Account Information".
JSPs: The files containing the text and forms that provide the user interface on the pages. JSPs are HTML pages with added JSP tags. You can use any text editor and some HTML editors to edit the JSPs. For information on modifying these pages, see "Editing JSPs".
HTML pages: The HTML registration page and files with common HTML code used by the JSPs. For example, the header.html file includes the HTML HEAD tag. You can use a text editor or HTML editor to edit these files. Cascading style sheet (CSS): The file that defines the appearance of the HTML pages. Edit this file to make global formatting changes, including fonts, text alignment, and margins. You can use a text editor or a CSS editor to edit this file. GIF files: The graphics displayed in the HTML pages. You can edit the files with a graphics program or replace them with your own graphics.
Important:
Before editing, make a copy of the default pages, including all HTML pages and JSPs, and edit and test the copies.
When you edit a Self-Care Manager file, you should edit the version located in the Self-Care Manager WAR file. This ensures that the customized files are used if you reconfigure your servlet engine for Self-Care Manager in the future. See "Modifying the Self-Care Manager WAR File". You can also use the Customer Center SDK to modify Self-Care Manager files from the WAR file. See "Using Customer Center SDK" and "Customizing the Self-Care Manager Interface" in BRM Developer's Guide.
Editing JSPs
JSPs use standard HTML formatting. In addition, the JSPs use special code to display information, or to display a text entry field for customer input. Each JSP tag starts with <% and ends with %>. You can move data input and display codes from one location on the page to another. You can also delete them. For example, if you do not offer the IP telephony service, you can delete all code that displays IP telephony information.
Important:
When editing JSPs, be careful to maintain the syntax when moving or deleting code. For example, a missing %> from a JSP tag will cause problems. When removing code, do not remove input entry points for information that is required for registration. See "Customizing the Self-Care Manager Interface" in BRM Developer's Guide. Do not copy data input and display codes from one page to another. Each code works only on the page that includes it.
For more information about editing JSPs, see Sun Microsystems JSP documentation or other JSP reference documents. For more extensive JSP customization, see "Customizing the Self-Care Manager Interface" in BRM Developer's Guide.
Copy the SelfCareManager_install_dir/WebKit/webkit_en.war file to a temporary directory. Extract the files from the WAR file using the jar command, as follows:
jar xvf webkit_en.war
3. 4. 5.
Delete or move the copy of webkit_en.war in the temporary directory. Edit any files in the htmlui_en directory. Create a new WAR file using the jar command from the temporary directory where you extracted the original files:
jar cvf webkit_en.war .
6.
When you set up Self-Care Manager as an application in your servlet engine, it will include the files you modified. If you have already set up Self-Care Manager in the servlet engine, copy the modified files to the correct location in the servlet engines directory.
These pages use the Business Application SDK (BAS) component collection (PIAComponentCollection) to hold BAS lightweight components (that is, PLightComponentHelper).
Self-Care Manager JSPs Description If the BRM server is brand-enabled, this JSP sets the scope to the correct brand, so that all information and data is specific to the subscribers brand. Enables customers to change the login name for a service. Enables customers to change a password. Enables customers to change account status. Defines strings for constants commonly used in other Self-Care Manager files. Enables error logging for debugging. Handles errors and displays error messages for all JSPs. Contains standard information displayed at the end of all JSPs. Enables customers to select the start time and end time used for generating the invoice. Used by other JSPs to retrieve commonly used account data saved during the session, such as the name and address for the account. Verifies the login name and password and displays confirmation when a customer logs in. Displays confirmation that a customer logged out and ends the session. Enables customers to pay an outstanding bill online with a credit card. Enables customers to search for records of online bill payments. The customer specifies a start date and end date. Enables customers to purchase additional plans. Enables customers to select the day, month, and year when specifying a time range for viewing account activity or invoices. Saves the current users session ID. Displays a customer invoice.
BrandSelect.jsp
change_login_form.jsp change_passwd_form.jsp change_status_form.jsp constants.jsp debug_errorlog.jsp error.jsp footer.jsp invoice_selection.jsp load_session.jsp login_verify.jsp logout.jsp online_payment.jsp online_payment_audit.jsp purchase_plan_form.jsp selection.jsp session_id.jsp show_invoice.jsp
Table 41 (Cont.) Self-Care Manager JSPs File name usage_report.jsp usage_selection.jsp Description Displays details about customer activity, such as a list of IP telephony calls. HTML pages use UsageReportGeneral.jsp instead. Enables customers to set the start and end dates for a usage report. For example, a customer can specify to see IP telephony calls for more than a single month. Included in the other usage report JSPs to do event search tasks that are common to all the usage report JSPs. Displays details about a customers content usage. Displays details about general customer activity, including cycle forward fees, purchase fees, adjustments, and IP and email usage. Other usage report JSPs display activity for specific types of usage. Displays details about a customers mobile data (GPRS) usage. Displays details about a customers mobile voice (GSM) usage. Displays details about a customers mobile messaging (SMS) usage. Included in the other usage report JSPs to display the data from a usage report on the Web page. Displays the customers account balance summary and has links to resource reservation, event search, and voucher top-up pages. Enables customers to specify which invoice to display. Displays information about a customers purchased products. Display the resource reservation details of a bill unit.
UsageReportGprs.jsp UsageReportGsm.jsp UsageReportSms.jsp UsageReportView.jsp view_balance.jsp view_invoice.jsp view_product.jsp AccountBalancePrepaid.jsp AccountBalancePrepaidView.jsp ReservationInfo.jsp ReservationInfoView.jsp Event_details.jsp Event_search.jsp eventsearch_dateselection.jsp Voucher_details.jsp
Style sheet: The HTML version of the JSPs use the style sheet infranet_ general.css. GIF files: The HTML version of the JSPs use several GIF files. Most are stored in htmlui_en/graphics, others are stored in htmlui_en.
5
5
This chapter describes how to automatically send messages to customers when they register and how to customize the messages in Oracle Communications Billing and Revenue Management (BRM).
Information about your plans. The customers connection settings, such as a new server address and mail server address. A list of phone numbers for dialup connections.
There are two ways you can send messages to your customers during online registration. You can use both methods:
You can display a message in a Web page during Web registration. This message typically confirms the plan that the customer has selected. The default introductory message is located in BRM_ Home/sys/cm/intro/default.intro. BRM_Home is the directory in which you installed the BRM software.
You can send email after a customer has registered. The default email welcome message is located in BRM_ Home/sys/cm/welcome/default.welcome.
Open the Connection Manager (CM) configuration file (BRM_ Home/sys/cm/pin.conf). Change the value of the new_account_welcome_msg entry to 1. 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
Change the value of the new_account_welcome_msg entry in the CM configuration file (BRM_Home/sys/cm/pin.conf) to 0 (default). Rename the default message file. Remove write permission on the default message file.
If the customer selects the Basic plan, the message says You have selected the Basic plan. Table 51 shows the default variables:
Table 51 Variables in Welcome Messages To insert this text Plan name Plan description Promotional code Example Basic Monthly Internet access Internet1
You can define more variables by customizing the PCM_OP_CUST_POL_GET_ INTRO_MSG policy opcode.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). (Optional) Change the sender entry. This entry changes the part of the email address that precedes the at sign (@); for example: sender@your_domain.com The default is postmaster.
3. 4.
Change the domain entry. This entry changes the part of the email address that follows the at sign (@), for example: Save and close the file. sender@your_domain.com
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the welcome_dir entry. 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.
If the customer selects the Basic plan, the message says You have selected the Basic plan. Table 52 shows the default variables:
Table 52 Variables Used in Introductory Messages To insert this text Plan name Plan description Promotional code Example Basic Monthly Internet access Internet1
You can define more variables by customizing the PCM_OP_CUST_POL_GET_ INTRO_MSG policy opcode.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the intro_dir entry. Save and close the file.
The new value becomes effective immediately and applies to the next account created. You do not need to restart the CM to enable this entry.
To choose the message, use the PCM_OP_CUST_POL_GET_INTRO_MSG policy opcode. To send the message, use the PCM_OP_CUST_POL_POST_COMMIT policy opcode. See "Adding Custom Account Creation Steps after the Account is Committed".
The PCM_OP_CUST_POL_GET_INTRO_MSG policy opcode uses the type of account and plan to determine which message to send, so you can specify how to send each type of message. The PCM_OP_CUST_POL_GET_INTRO_MSG policy opcode reads the message from the file specified in the CM pin.conf file intro_dir entry. See "Changing the Introductory Message Location".
The PCM_OP_CUST_POL_GET_INTRO_MSG policy opcode returns the introductory message as an uninterpreted buffer of data. This allows the introductory message to include HTML, graphics, and other complex information. Within each introductory message, a parameter substitution system allows the message to contain values that are specific to this customer, such as the name of the plan they have chosen for purchase. For example, the following allows you to substitute a plan and a promotional code name:
You are requesting to purchase the ${price_plan} plan via the ${promo_code} promo code.
The substitution is handled by the following code in the PCM_OP_CUST_POL_GET_ INTRO_MSG policy opcode:
/************************************************************* * Price Plan 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); }
For example, you could identify which message to send by using the IP address that the user logged in to. In that case, an introductory message file name might be: 156.151.1.11.1700.intro
Sending Registration Information to Customers 5-5
In this example:
156.151.1.11 is the IP address 1700 is the port number intro is the suffix
6
6
The Credit Card Info tab and the Invoice Info tab may contain duplicate information. If you edit information on either tab, ensure that you make the same changes to the other. If the customer has purchased an email service, BRM assigns an email address based on the login for the service. To change the email address, you must change the login. See "Changing Login Names".
Sets the billing address in the accounts 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).
Important:
The PCM_OP_CUST_CREATE_ACCT opcode calls PCM_OP_CUST_SET_ NAMEINFO as part of the process of creating an /account storable object. If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_NAMEINFO creates an /event/customer/nameinfo storable object to record the details of the operation. If the operation is successful, PCM_OP_CUST_CREATE_ACCT returns the BRM object ID (POID) of the /event/customer/nameinfo object in the PIN_FLD_RESULTS array. If PCM_OP_CUST_CREATE_ACCT fails, it returns a PIN_FLD_FIELDS array that specifies the failing field.
PCM_OP_CUST_POL_PREP_NAMEINFO. See "About the PREP and VALID Opcodes" in BRM Developer's Guide. PCM_OP_CUST_POL_VALID_NAMEINFO. See "About the PREP and VALID Opcodes" in BRM Developer's Guide.
PCM_OP_CUST_SET_NAMEINFO calls the PCM_OP_CUST_POL_PREP_ NAMEINFO policy opcode to prepare the customer information for validation and to determine whether the account being created is the BRM payment suspense account. The PCM_OP_CUST_POL_PREP_NAMEINFO policy opcode 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, the PCM_OP_CUST_POL_PREP_NAMEINFO policy opcode 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 policy 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 policy 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 the PCM_OP_CUST_POL_VALID_ NAMEINFO policy opcode to validate the information.
After you edit this list, recompile the code to make your changes take effect. For information on the PCM_OP_CUST_POL_VALID_NAMEINFO policy opcode, see PCM_OP_CUST_POL_VALID_NAMEINFO and "About the PREP and VALID Opcodes" in BRM Developer's Guide.
To customize the creation of the locale, use the PCM_OP_CUST_POL_PREP_ LOCALE policy opcode. The default implementation does nothing. See "About the PREP and VALID Opcodes" in BRM Developer's Guide. To customize how to validate the locale, use the PCM_OP_CUST_POL_VALID_ LOCALE policy opcode. See "About the PREP and VALID Opcodes" in BRM Developer's Guide. The PCM_OP_CUST_POL_VALID_LOCALE policy opcode 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. See BRM locale IDs for a list of the valid BRM locales.
How customers find out about your business. Services that your customers would like you to offer. Account numbers from legacy customer management systems. Information necessary to offer some services. For example, you might need to assign nicknames for a chat service.
The information you collect is stored in account profiles. You can use information in profiles in various ways; for example:
You can create applications that search for information in profiles. For example, you could create a friends-referral program by creating a profile that collects referrals. When a customer registers, you can search profiles to find which customer made the referral and give that customer a credit. You can read information from an account profile and use it as input to custom applications and configurations. For example, you could base custom rates on values in a profile.
To add a /profile object to an account, use the PCM_OP_CUST_CREATE_ PROFILE opcode. 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 storable object that contains extra information that you
want to store about an account and associates it with the account storable object POID.
To modify a profile object, use the PCM_OP_CUST_MODIFY_PROFILE opcode. 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.
Use the PCM_OP_CUST_POL_PREP_PROFILE policy opcode to add custom data to the /profile object. See "About the PREP and VALID Opcodes" in BRM Developer's Guide. Use the PCM_OP_CUST_POL_VALID_PROFILE policy opcode to validate the data in the /profile object. See "About the PREP and VALID Opcodes" in BRM Developer's Guide.
To display profile information in Customer Center, you must configure Customer Center by using Customer Center SDK. See "Using Customer Center SDK" in BRM Developer's Guide.
The percent sign is the only wildcard you can use with this
field.
7
7
This chapter describes how to manage Oracle Communications Billing and Revenue Management (BRM) customer authentication, including login names, passwords, and security codes.
By default, the login name can be a minimum of 1 character and a maximum of 255 characters. By default, the password must be a minimum of 1 character and a maximum of 255 characters. A login name can be assigned to only one account. Login names are unique.
All login names and passwords are associated with a service; for example, the IP service. Customer service representatives (CSRs) use a login name and password to log in to the admin_client service.
Note:
Changing the customers email login name also changes the customers email address. Before changing a login name, make sure the customer wants to change the email address.
For more information, see "Setting Up Login Name and Password Defaults".
Managing Customer Authentication 7-1
Customers use service passwords, such as the password that a customer provides when logging in to an Internet connection, to access an IP service. Customers use account passwords for non-IP access, such as accessing a Web page.
By default, account passwords are stored in the database in an encrypted format; service passwords are not. For more information about encryption, see "About Encrypting Information" in BRM Developer's Guide.
Customers can change their security codes at any time. Security codes are not validated by BRM. See "Using Customer Security Codes".
Changing the customers login name for an email service also changes the customers email address for the service. Before changing a login name, make sure the customer wants to change the email address.
Changing Passwords
Use Customer Center to change passwords. If you want customers to change their own passwords, create a Web page that allows customers to change their account information. See "Ways to Implement a Web Interface". Typically, a customers password must be changed in two places:
To change the password on the customers computer, have the customer locate their password file and make the change. The name and location of the password file differ depending on the configuration of the customers connection software. For example, if your customer uses Netscape, the password file is usually located in the netscape\dialer\ISP.sr file, where ISP is the name of your company. However, because customers can change the default location of their password file when they install their connection software, they might have trouble finding this file.
Change the password in Customer Center on the Service tab. Have this customer reconfigure the dial-in software with the new password. You can also set up BRM to charge a fee for changing the password. See "About Charging for Administrative Events" in BRM Setting Up Pricing and Rating.
If the customer cannot change the password in the dial-in software, have the customer contact the company that produces the dial-in software to find out if theres a way to locate the lost password. If the customer cannot find or change the password, close the current BRM account and open a new one. This may be the easiest method for many customers. The drawback to this method is that closed accounts remain in your companys database. See "Reusing Login Names and Passwords from Closed Accounts or Canceled Services".
Standardizing how account names are displayed, regardless of how they are entered. For example, you can remove spaces from the name or capitalize the first and last name. See "Standardizing Account Names". Defining the required case-sensitivity of email logins. See "Defining Email Login Names". Detecting duplicate logins. See "Detecting Duplicate Logins". Defining how to encrypt passwords. "About Encrypting Customer Passwords".
Require the customer to specify a password. This is the default. Generate a password automatically for the customer.
To generate a password for the customer, you must supply the algorithm for generating passwords. To do so, customize the PCM_OP_CUST_POL_PREP_PASSWD policy opcode.
The email login must use all lowercase characters. The email login must include the domain, in this format:
login@domain
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 storable object in the PIN_FLD_RESULTS array. Otherwise, only the Portal object ID (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 storable object to record the details of the operation.
To prepare login names, use the PCM_OP_CUST_POL_PREP_LOGIN policy opcode. For example, you can add characters or change the case to all lowercase. See "About the PREP and VALID Opcodes" in BRM Developer's Guide. To validate login names, use the PCM_OP_CUST_POL_VALID_LOGIN policy opcode; for example, to ensure that they have the required number of characters, See "About the PREP and VALID Opcodes" in BRM Developer's Guide. You define login validation rules by using the Field Validation Editor. This application loads validation rules into the /config/fld_validate storable object. By default, login names must be 255 characters or fewer.
Caution: BRM requires logins for services (they cannot be NULL). BRM requires that login names be unique. BRM will not function properly if the PCM_OP_CUST_POL_VALID_LOGIN policy opcode is customized to allow non-unique login names.
The PCM_OP_CUST_POL_PREP_LOGIN policy opcode converts all NULL login names to an empty string. For example, if the service type is /service/email and the policy opcodes PIN_FLD_LOGIN input flist field is set to NULL, the policy opcode changes the PIN_FLD_LOGIN flist field to "". The PCM_OP_CUST_POL_VALID_LOGIN policy opcode 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 IP services without supplying a login name, customize the PCM_OP_CUST_POL_PREP_LOGIN policy opcode to skip the conversion of NULL login names to an empty string.
Creating Passwords
In cases where a prepaid service login is needed, such as Self-Care Manager, the customers Mobile Station Integrated Services Digital Network (MSISDN) number is stored in the service object PIN_FLD_ALIAS_LIST array. See "About Using BRM for Wireless Services" in BRM Telco Integration. The PCM_OP_CUST_POL_VALID_LOGIN policy opcode 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. See "About Telco Service Logins and Passwords" in BRM Telco Integration.
Creating Passwords
For information about how passwords are used in BRM, see "About Login Names and Passwords". To add or change passwords, use the PCM_OP_CUST_SET_PASSWD opcode. This opcode sets the PIN_FLD_PASSWD field for a specified /service storable 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 storable object to record the details of the operation. Before setting the new password value, PCM_OP_CUST_SET_PASSWD calls the following policy 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 storable 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 policy opcodes to customize passwords:
To prepare account or service passwords for validation, use the PCM_OP_CUST_ POL_PREP_PASSWD policy opcode. This policy opcode takes the password field for an /account or /service storable object during customer registration and prepares it for validation. If the password is for an account, it is set to NULL.
Creating Passwords
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 the PCM_OP_CUST_POL_VALID_ PASSWD policy opcode. The default check is to make sure the password is not NULL and is less than 255 characters.
The PCM_OP_CUST_POL_COMPARE_PASSWD policy opcode takes a cleartext password and an encrypted password from the PCM_OP_CUST_POL_ ENCRYPT_PASSWD policy opcode 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 storable object whose password is being compared is included in the input flist, so the encryption mechanism can be varied for different storable object types. The PCM_OP_CUST_POL_COMPARE_PASSWD policy opcode returns true (match) or false (no match). The PCM_OP_CUST_POL_ COMPARE_PASSWD policy opcode is used by BRM whenever a client application supplies a password to be authenticated against an /account or /service storable object. The PCM_OP_CUST_POL_DECRYPT_PASSWD policy opcode decrypts a cleartext password.
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.
For more information, see "Managing CSR Passwords" in BRM Developer's Guide.
Log in with the wrong password Log in to an inactive service Log in after exceeding their credit limit
You can also record successful logins, although doing this slows BRM performance.
Edit the BRM_Home/sys/data/config/pin_verify file, where BRM_Home is the directory in which you installed the BRM software. The pin_verify file includes examples and instructions. You can make these types of changes:
Edit a list of predefined types of login failures to specify which events you want to record and to modify their descriptions. Add custom types of login failures you want to record.
Caution: When you run load_pin_verify, it overwrites the existing preferences for recording customer login failures. If you are updating your preferences, you cannot load new preferences only. You must load complete sets of preferences each time you run the load_pin_ verify utility.
2.
3.
To verify that the network elements were loaded, you can display the /config/verify object by using Object Browser, or by using the robj command with the testnap utility. (See "Reading an Object and Writing its Contents to a File" in BRM Developer's Guide.)
(Optional) Use Customer Center to create an account specifically for logging verification events. You can create a CSR account or a dummy account. If you create a dummy account, you should:
Use a dummy plan that includes no rates and has a purchase level of all accounts and no services. Use the internal payment method. Use any name and address you want. You have to enter something for name and address to create an account.
2. 3.
Open the CM configuration file in BRM_Home/sys/cm. Add this entry to the end of the file:
- fm_act account_name database_number /account 1
where account_name is the name of the account to which verification logging should go; database_number is the database number of the BRM database. By default, this number is 0.0.0.1. This example sets an account called verify_acct to log verification events:
- fm_act verify_acct 0.0.0.1 /account 1 4. 5.
Save the file. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Use Customer Center to open the root account or the account you specified in the CM configuration file. Open Event Browser. Search for verification activity events. Following are two examples of how to do this:
If you have an account set up especially to log verification events, you can search for all events logged to that account.
If you are using root or another account that is logging many types of events, you can use the Any Event (Advanced) template in the Search dialog box to search only for events of the type /event/activity/verify.
PCM_OP_ACT_FIND_VERIFY is the recommended opcode for authenticating customers. See "Authenticating User Actions". PCM_OP_ACT_FIND. See "Finding a Customers Account Information". The PCM_OP_ACT_POL_SPEC_VERIFY policy opcode. See "Customizing Authentication Checks".
Calls PCM_OP_ACT_FIND to retrieve the users /account and /service objects. See "Finding a Customers Account Information". Calls the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode to retrieve the list of authentication checks for the specified action. See "Customizing Authentication Checks". Performs all authentication checks specified by the policy opcode. Returns the following, depending on the success of the transaction:
3. 4.
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.
If you use a multidatabase BRM system, it searches all databases to find the /account object. If there is an open context (CM connection) to a database when it is called and it finds the account in a different database, it switches the context to the correct database. If there is no open context when it is called, it searches all databases.
Note:
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 storable object, not just the POID.
7-11
Table 71 (Cont.) Default Authentication Checks Authentication check PIN_ACT_CHECK_SRVC_PASSWD PIN_ACT_CHECK_CREDIT_AVAIL PIN_ACT_CHECK_DUPE_SESSION Enum value 6 7 8 Description Confirm that the password is correct. Check the available credit. 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. See the output flist specification for more details. Table 72 shows the authentication checks that the PCM_OP_ACT_POL_SPEC_ VERIFY policy opcode returns and their behavior:
Table 72 Action PCM_OP_MAIL_DELIV_VERIFY PCM_OP_ACT_LOGIN Authentications Checks Returned by PCM_OP_ACT_POL_SPEC_VERIFY Default authentication checks PIN_ACT_CHECK_SRVC_STATUS = active 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 PCM_OP_TERM_IP_DIALUP_ AUTHORIZE PIN_ACT_CHECK_SRVC_STATUS = active PIN_ACT_CHECK_SRVC_PASSWD PIN_ACT_CHECK_CREDIT_AVAIL = >=0 PCM_OP_TERM_IP_DIALUP_ AUTHENTICATE/CHAP PCM_OP_TERM_IP_DIALUP_ AUTHENTICATE DEFAULT (for everything else) PIN_ACT_CHECK_SRVC_STATUS = active PIN_ACT_CHECK_SRVC_PASSWD PIN_ACT_CHECK_SRVC_STATUS = active
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.
The PCM_OP_ACT_POL_SPEC_VERIFY policy opcode uses the DEFAULT set of authentication checks on any action it does not recognize. If you want to specify a different set of authentication checks for a new action, you must:
7-12 BRM Managing Customers
1. 2.
Edit the BRM_Home/source/sys/fm_policy/fm_act_pol/fm_act_pol_spec_vrfy.c source file. Create a new Activity Policy Facilities Module (FM). See "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide. 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 have defined a non-currency resource. If you want to enforce a credit limit on that resource, you must modify the fm_act_pol_spec_vrfy.c file to include a new action that checks the non-currency resource balance. (By default, checks are performed only on the currency resource.) Reducing the number of authentication checks does not have a significant effect on performance, with the exception of duplicate session checking.
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. 3.
Add the same code fragment at line 390. Recompile the file and use it as a new Activity Policy FM.
7-13
8
8
"Related Documents" in BRM Email Manager "Configuring Payment Fees" in BRM Configuring and Collecting Payments "Configuring Payment Incentives" in BRM Configuring and Collecting Payments
An account can belong to more than one customer segment. The customer segments are defined in the /account object PIN_FLD_CUSTOMER_SEGMENT_LIST field. The customer segment rules apply to all accounts that belong to the customer segment.
8-1
To assign customer segment information to an account during account creation, see "Implementing Customer Segment Information".
Editing the pin_customer_segment.xml File Loading Customer Segments into BRM Validating the pin_customer_segment.xml File
To assign customer segment information to an account during account creation, see "Implementing Customer Segment Information".
Minimum length is 0 characters. Maximum length is 1023 characters. Note: This string is mapped to the PIN_FLD_DESCR field in the /config/customer_segment object.
Important:
The load_pin_customer_segment utility needs a configuration file (pin.conf) in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Caution: The load_pin_customer_segment utility overwrites existing customer segments. If you are updating customer segments, you cannot load new customer segments only. You must load complete sets of customer segments each time you run the load_pin_ customer_segment utility.
Open the pin_customer_segment.xml file (BRM_Home/sys/data/config) by using an XML editor or a text editor. See "Editing the pin_customer_segment.xml File" for more information.
2. 3.
Customer segment IDs in the 0 - 1000 range are reserved by BRM. The default customer segment ID is 0, and all accounts belong to this customer segment by default.
4.
Important:
The pin_customer_segment.xml file is referenced by the pin_business_configuration.xsd file; therefore, these files must be located in the same directory. By default, the location is BRM_ Home/sys/data/config.
If you do not run the utility from the directory in which the XML and XSD files are located, include the complete path to the files, for example:
load_pin_customer_segment BRM_Home/sys/data/config/pin_customer_segment.xml 5. 6.
Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide. (Optional) To verify that the customer segments were loaded, display the /config/customer_segment object by using Object Browser or by using the robj command with the testnap utility. See "Reading an Object and Writing its Contents to a File" in BRM Developer's Guide.
8-3
This parameter validates the contents against the XML files schema definition before loading the data into the /config/customer_segment object.
Note:
The schema definition for the pin_customer_segment.xml is in the BRM_Home/xsd/pin_customer_segment.xsd file. This file uses the pin_business_configuration.xsd reference file to perform additional processing.
For more information, see "About Validating XML Configuration Files" in BRM System Administrator's Guide.
Note: Accounts created outside of Customer Center are assigned a customer segment value of 0.
9
9
The mailing address for the invoice. If the invoice recipient is the same as the account holder, this information should be the same as the customer contact information. How to deliver the invoice (postal mail or email). If you choose email, you enter the email address.
If you want the account holders information to reflect the new billing information, update the contact information for the account after you have updated the invoice information. See "Customizing Customer Payment Information" for more information about changing a customers invoice information.
For security reasons, the Visa CVV2 numbers and American Express CID numbers are not stored in the BRM database; however, you can configure BRM to send them to the credit card processor when a credit card is added to an account or changed in an account if they are required for authorization. See "Requiring Additional Protection Against Credit Card Fraud" in BRM Configuring and Collecting Payments.
9-1
The billing information for accounts is typically listed as the primary account contact. If you want the account holders information to reflect the new billing information, update the contact information for the account after you have updated the credit card information. Use Customer Center to change credit card information. See the discussion on changing credit card information in BRM Customer Center Online Help.
About Changing an Accounts Bill Unit to the Nonpaying (Subordinate) Payment Method
If you change a child account bill units payment method to nonpaying (subordinate) after creating the account, the billing information for the nonpaying bill unit changes to match the parent account. A nonpaying bill unit must use the same currency, billing date, billing frequency, and accounting type as its parent account. If the accounts use two currencies, the parent account and the nonpaying bill unit in the child account must use the same primary currency. See the discussion on moving an account between hierarchical groups in BRM Customer Center Online Help.
PCM_OP_CUST_CREATE_PAYINFO is called by PCM_OP_CUST_UPDATE_ CUSTOMER when a customers payment information is modified. For more information, see "Modifying an Account". 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.
To customize how /payinfo objects are created, use the following opcodes:
PCM_OP_CUST_POL_PREP_PAYINFO. See "Customizing Payment Method Data Preparation" and "About the PREP and VALID opcodes" in BRM Developer's Guide. PCM_OP_CUST_POL_VALID_PAYINFO. See "Customizing Payment Method Validation" and "About the PREP and VALID opcodes" in BRM Developer's Guide. PCM_OP_CUST_FIND_PAYINFO. See "Finding Payment Info". PCM_OP_PYMT_POL_SPEC_VALIDATE. See "Customizing the Account Used for Credit Card Validation".
To delete a /payinfo object, use the PCM_OP_CUST_DELETE_PAYINFO opcode. This opcode is given the /payinfo object Portal object ID (POID) of the object to delete.
Note:
You cannot delete a /payinfo object that is currently associated with a /billinfo object; you must first delete the /billinfo object.
If you have customized objects related to payment for an account, then, before you delete the /payinfo object for the account, you need to take steps to ensure that the deletion will not affect any customized information associated with that payment setup. To do so, use the PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode. The PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode is called by the PCM_OP_CUST_DELETE_PAYINFO opcode before the latter opcode deletes the /payinfo object. The PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode 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 opcode. For more information on the PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode, see BRM Developer's Reference.
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 registration. If the payment method is dd (US and Canadian direct debit), the /payinfo/dd object is created and the information is prepared for online registration.
9-3
If the payment method is cc or dd, the PCM_OP_CUST_POL_PREP_PAYINFO policy opcode 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 policy opcode.
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".
Is the debit number acceptable? (checksum) Is the debit number an acceptable type? Has the expiration date passed?
Is the bank number acceptable? (9 digits) Is the debit number acceptable? (11 digits) What is the account type? (checking, corporate checking, savings)
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, the PCM_OP_CUST_CREATE_PAYINFO and the PCM_OP_ CUST_MODIFY_PAYINFO opcodes omit the PIN_FLD_SECURITY_ID field from the input flist of the PCM_OP_CREATE_OBJ opcode 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, the PCM_OP_PYMT_CHARGE opcode 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 Connection Manager (CM) pin.conf files 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. For information on how to make these values required or optional, see "Requiring Additional Protection Against Credit Card Fraud" in BRM Configuring and Collecting Payments.
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.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). BRM_Home is the directory in which you installed the BRM software. Change the flag in the cc_checksum entry from 1 (enable) to 0 (disable):
- fm_cust_pol cc_checksum 0
3.
The new value becomes effective immediately and applies to the next account created. The CM does not need to be restarted.
9-5
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. The PCM_OP_PYMT_POL_SPEC_VALIDATE policy opcode reads the following CM pin.conf file entries:
The cc_validate entry, which specifies whether to validate credit cards. See "Validating Credit Cards at Registration". The cc_revalidate entry, which specifies the amount of time before revalidation is required. See "Revalidating Credit Cards".
In addition, the PCM_OP_PYMT_POL_SPEC_VALIDATE policy opcode 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.
Note:
If you create accounts that have custom payment methods, you must modify the PCM_OP_CUST_POL_PREP_PAYINFO policy opcode to validate them. For example, add code for your custom payment method everywhere the opcode checks the various payment methods.
Use the information in the following tables to edit the predefined payment methods and element IDs in the /config/payment object:
Payment Methods and Element IDs Opcodes Using PIN_FLD_PAY_TYPE Fields in PIN_FLD_PAY_TYPE
See pin_pymt.h in the BRM_Home/include directory for a complete list of supported payment methods. Table 91 list the payment methods and element IDs.
Table 91 Payment Methods and Element IDs Element ID 0
Payment method PIN_PAY_TYPE_UNDEFINED Used during account creation. PIN_PAY_TYPE_PREPAID Used to keep negative balances. PIN_PAY_TYPE_INVOICE Used for monthly invoices. PIN_PAY_TYPE_DEBIT Used for checking account debit. PIN_PAY_TYPE_CC Used for credit cards. PIN_PAY_TYPE_DD Used for US/Canadian direct debits. PIN_PAY_TYPE_SMARTC Used for smartcards. PIN_PAY_TYPE_SUBORD Used to roll up balances to the parent account. PIN_PAY_TYPE_BETA For use by beta testers only. Billing utilities ignore this. PIN_PAY_TYPE_INTERNAL Used for internal employees. Used the same way as guest accounts. PIN_PAY_TYPE_GUEST Used for guest accounts. It is not charged, but credit limits apply. PIN_PAY_TYPE_CASH Used for cash.
10000
10001
10002
10003
10005
10006
10007
10008
10009
10010
10011
9-7
Table 91 (Cont.) Payment Methods and Element IDs Payment method PIN_PAY_TYPE_CHECK Used for personal bank checks. PIN_PAY_TYPE_WTRANSFER Used for wire transfers. PIN_PAY_TYPE_PAYORDER Used for inter-bank payment orders. PIN_PAY_TYPE_POSTALORDER Used for postal payment orders. PIN_PAY_TYPE_VOUCHER Used for payment vouchers. PIN_PAY_TYPE_FAILED Used for unconfirmed payments that failed. 10017 10016 10015 10014 10013 Element ID 10012
Note:
To avoid conflicts with payment IDs reserved by BRM, custom payment methods should be defined with an element ID greater than 10099.
Important:
If a customer makes a payment with a payment method that has not been saved with an account, you must add the new payment method, when first used, to the input flist of the following opcodes. For example, this is required if an invoice customer makes a one-time payment by using a new credit card. (This is not required if the payment method was defined when the account was created.)
Opcode name PCM_OP_PYMT_CHARGE PCM_OP_PYMT_CHARGE_CC PCM_OP_PYMT_COLLECT PCM_OP_BILL_GROUP_DELETE_MEMBER PCM_OP_BILL_MAKE_BILL PCM_OP_BILL_MAKE_BILL_NEW PCM_OP_BILL_MAKE_BILL_ON_DEMAND PCM_OP_BILL_MAKE_BILL_RCV_PAYMENT PCM_OP_PYMT_RECOVER PCM_OP_BILL_REVERSE PCM_OP_BILL_REVERSE_PAYMENT PCM_OP_PYMT_VALIDATE
PIN_FLD_NAME The name of the opcode to be associated with this pay type.
PIN_FLD_OPCODE The number of the opcode to be associated with this pay type.
Value/Element ID 0 1 2 3
Using a text editor, edit the file to add an element to the PIN_FLD_PAY_TYPES array for each new payment method.
For a predefined payment method, use the appropriate value as the index for that element of the PIN_FLD_PAY_TYPES array. See " Payment Methods and Element IDs". For a custom payment method, define a payment method in a header file and use that value as the index of the new element in the PIN_FLD_PAY_TYPES array.
9-9
Important:
To avoid conflicts with payment IDs used by BRM, define custom payment methods with an element ID of 10100 or higher.
2. 3.
Save and close the file. Use the testnap utility to load the /config/payment object into the database. See "Testing your Applications and Custom Modules" in BRM Developer's Guide.
where database_number is the database number of the BRM database. By default, this number is 0.0.0.1. Replace 200, the default POID of the /config/payment object, with the POID of the new object.
3.
Using Customer Center. Calling the PCM_OP_CUST_SET_BILLINFO opcode in an application and setting the value of PIN_FLD_PAY_TYPE to PIN_BILL_TYPE_UNDEFINED (0). By default, credit limits are set to 0. Because an account with a payment method of Undefined never pays a bill, you need to set the credit limit to Unlimited.
Important:
Because billing cycles are whole multiples of accounting cycles, the only cycle fee proration that might occur is for multi-month cycle rates. A child account with a subordinate bill unit must use the same currency, billing frequency, billing day of the month, and accounting type as its parent account.
9-11
For nonpaying bill units, BRM uses the credit limit of the parent (paying) accounts receivable (A/R) bill unit to determine whether the nonpaying bill units credit limit is reached.
You define credit limits in plans. For example, a plan might include a credit limit of $200. You change an individual customers credit limit by using Customer Center. You can also define credit thresholds to alert customers when the credit limit is about to be reached. You use event notification to alert customers automatically. See "About Applying Credit Limits to Resources" in BRM Setting Up Pricing and Rating. You can set credit limits for currency resources and non-currency resources.
Note:
If the account uses a secondary currency, you need to set the credit limit in the primary currency. See Managing Currencies in Customer Accounts.
Use Pricing Center to set credit limits for plans. See BRM Pricing Center Online Help. Use Customer Center to set or change credit limits. See BRM Customer Center Online Help.
When you create your price plans, if two services have different credit limits, create new balance groups for the services. This allows credit limits for each service to be set and tracked independently. See "Tracking Resources by Service" in BRM Setting Up Pricing and Rating. Specify which credit limit takes precedence when a new credit limit conflicts with an existing credit limit. You do this by setting the credit_limit_conflict entry in the CM configuration file.
replace, to use the new credit limit. ignore, to ignore the new credit limit and keep the existing credit limit.
add, to add the new credit limit to the existing credit limit and create a new limit. minimum, to use the credit limit that specifies the smaller amount. maximum, to use the credit limit that specifies the greater amount.
If this entry is not present, the new credit limit is used by default.
3.
Denies all authorization requests. This prevents an account from logging in or using services until the account balance falls below the credit limit. Stops rating events associated with the account. BRM rates events up to the credit limit amount and then returns any remaining usage as unrated.
To prevent revenue leakage, you can configure BRM to rate all events as defined in the rate plan, regardless of whether the account balance exceeded the limit. You configure whether BRM ignores credit limit settings during the rating process in three different ways as shown in Table 95.
Table 95 Override Product-level override Ways to Override Credit Limit Settings Event type Actual event Description Specifies to ignore credit limit settings when rating the specified product. When a resource has exceeded a credit limit, BRM uses the credit limit override rate to rate the specified product. This product-level setting takes precedence over the system-wide default setting. See the discussion on Defining Rates in BRM Pricing Center Online Help. Note: This setting does not affect prepaid AAA events, which are always checked against the credit limit. System-wide default Actual event Specifies to ignore the credit limit setting during the rating process. See "Configuring the System-Wide Override Credit Limit". Note: This setting does not affect prepaid AAA events, which are always checked against the credit limit. Calc-only override Calc-only Specifies to ignore credit limit settings during Calc-only rating. event You use this setting for Calc-only events that do not require credit limit checks, such as for best pricing rating or prepaid top-ups. You override credit limit checks during Calc-only rating by passing the PIN_RATE_FLG_OVERRIDE_CREDIT_LIMIT flag in the PIN_FLD_FLAGS input flist field of an opcode.
Note:
Even when BRM is configured to enforce all credit limit settings, BRM may still ignore credit limits during real-time pipeline discount rating and charge sharing.
9-13
When this feature is enabled, the rating engine applies the full cycle-forward fee and full usage fee. When this feature is disabled, the rating engine applies part of the cycle-forward fee or usage fee until the credit limit is reached.
Note:
Tax amounts are applied even if the credit limit has been exceeded and the OverrideCreditLimit entry is disabled.
This command creates an editable XML file named bus_params_rating.xml.out in your working directory. If you do not want this file in your working directory, specify the path as part of the file name.
2.
3.
enabled specifies to ignore all account credit limit settings during the rating process. BRM continues to enforce credit limits during the authorization process. disabled specifies to enforce credit limit settings. This is the default setting.
4.
This command loads your changes into the rating instance of the /config/business_params object.
Caution: BRM uses the XML in this file to overwrite the existing rating instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRMs rating configuration.
5. 6.
Read the object with the testnap utility or Object Browser to verify that all fields are correct. Stop and restart the CM.
7.
Real-time rating: Credit threshold checks are performed for both currency and non-currency resources. To configure real-time rating to perform credit threshold checks, see "Configuring Event Notification for Threshold Checking". Batch rating: Credit threshold checks are performed for only non-currency resources, such as minutes. To configure batch rating to perform credit threshold checks, see "Configuring Event Notification for Threshold Checking" and "Setting Up the Batch Rating Process to Perform Threshold Checking".
Note: Performing credit threshold checking during batch rating decreases pipeline processing performance. See "Enabling Threshold Checking in Pipeline Manager".
By setting the credit floor to 0, the credit threshold to 90%, and the credit limit to 100 minutes. By setting the credit threshold to 90 minutes.
In the above example, if credit floor is set to 10 and the credit threshold is 90%,
the threshold will be 100, for a credit limit of 110. the threshold will be 91, for a credit limit of 100.
You set or modify credit threshold values in your plans by using Pricing Center. After a customer purchases a plan, you can change the customers individual credit threshold values by using Customer Center.
Note:
Customer Center can modify only percentage threshold values. To modify fixed threshold values, you must customize your client application to call the PCM_OP_BILL_SET_LIMIT_AND_CR opcode. See "Customizing Client Applications to Modify Fixed Thresholds".
9-15
/event/notification/threshold when the balance crosses above the credit threshold value due to a new balance impact. /event/notification/threshold_below when the balance falls below the credit threshold value due to a customer payment or an adjustment.
These notification events trigger a call to the opcode specified in the /config/notify object. By default, the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode is called. This policy opcode processes the event data and passes information to Customer Center or your custom client application. You can customize the policy opcode to perform other actions, such as sending an email to the customer. To alert customers when credit thresholds are breached, you must configure the event notification feature, the policy opcode, and your custom client application to process these events and alert customers. For more information, see "Configuring Event Notification for Threshold Checking".
When balance impacts are applied during real-time rating. For more information, see "About Credit Limit and Threshold Checking during Real-time Rating". When balance impacts are applied during batch rating. For more information, see "About Credit Limit and Threshold Checking during Batch Rating".
Note:
The utility that loads balance impacts into the BRM database is different from the utility that loads threshold breach notifications into BRM. Therefore, the customer's balance may not immediately reflect the balance on the threshold breach notification.
When a credit profile is modified and balance monitoring is enabled. After a customers credit threshold values are updated in the credit profile, BRM determines whether the customers balance has breached any of the new threshold values.
compares the customers current balance to the updated credit floor, credit limit, and credit threshold values that are stored in the customers credit profile (/config/credit_ profile object). If the balance has breached a credit threshold value, BRM generates a notification event. To enable custom client applications to perform credit threshold checks during the real-time rating process, configure your client application to pass information in the input flist of the PCM_OP_BILL_SET_LIMIT_AND_CR opcode. For more information, see "How BRM Handles Consumption Rules and Credit Limits".
Pipeline rating calculates balance impacts and credit threshold breaches immediately. However, the utility that loads the balance impacts into the BRM database is different from the utility that loads credit threshold breaches into BRM. This means that a notification for a credit threshold breach might be sent before the customers balance is updated in the BRM database. Therefore, the customer balance shown on the threshold breach notification may temporarily be different than the balance in the customers account.
The following pipeline modules are responsible for checking credit thresholds during the batch rating process:
DAT_PortalConfig retrieves credit profile information from the BRM database and stores it in its internal memory. DAT_BalanceBatch retrieves the customers current credit profile from the DAT_ PortalConfig module, compares the customers updated balance to the credit profile, and notifies FCT_ApplyBalance if a credit threshold or credit limit has been breached. FCT_ApplyBalance updates the customers current balance in the DAT_ BalanceBatch internal memory and, if a credit threshold has been breached, writes the EDR into an internal list. To help you identify the exact event that caused the threshold breach, FCT_ ApplyBalance adds the following event attributes to each threshold breach notification: Event type (DETAIL.EVENTTYPE) Call originator (DETAIL.A_NUMBER) Call destination (DETAIL.B_NUMBER)
At the end of the transaction, FCT_ApplyBalance writes all of the EDRs from the internal list to an XML output file. See "About the Format of the XML Output File Name". After the XML output file is generated, Batch Controller uses the load_notification_ event utility to load the notification events into BRM. See "About Loading Notifications from Pipeline Manager to BRM".
9-17
OutputPrefix is the prefix name specified in the OutputPrefix registry entry. PipelineName is the name of the individual pipeline, such as ALL_RATE. StreamName is based on the unitsPerTransaction parameter maintained at the input level of the pipeline. A value of 1 means that one input file generates one output file. A value of more than one means that multiple input files are merged into one output file. StreamName is replaced with the name of the last file merged into the output file. For example, if unitsPerTransaction was 3 and the files merged into the output file were file01, file02, and file03, StreamName would be replaced with file03. TransactionID is the system-generated transaction ID number. SequenceNumber signifies the order in which FCT_ApplyBalance created the XML output file within a transaction. For example, the first XML output file has a sequence number of 1, the second output file has a sequence number of 2, and so on.
For example:
balancenotification_ALL_RATE_file01_776_1
Batch Controller launches the SampleLoadHandler batch handler. SampleLoadHandler moves the output XML file to a processing directory and runs the load_notification_event utility. load_notification_event converts the notification events in the output XML file into flist format and loads them into BRM. The BRM event notification system sends an alert to the customer. See "About Alerting Customers when Credit Thresholds are Breached". SampleLoadHandler determines whether the utility successfully loaded the notification events into BRM:
If the utility was successful, SampleLoadHandler moves the output XML file from the processing directory to the archive directory. If the utility failed, SampleLoadHandler moves the output XML file from the processing directory to the reject directory.
You must configure Batch Controller, the batch handler, and the load_notification_ event utility to process the output XML files. See "Configuring Batch Controller to Run load_notification_event".
Customize the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode to process threshold breaches. You can add custom code to this policy opcode so that it alerts the CRM client application or sends an email to the customer. For information, see "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide. Configure event notification to call a different opcode by editing the BRM_ Home/sys/data/config/pin_notify file and running the "load_pin_notify" utility. For information, see "Implementing Event Notification" in BRM Developer's Guide.
Enable threshold checking. See "Enabling Threshold Checking in Pipeline Manager". Configure Batch Controller to run the load_notification_event utility. See "Configuring Batch Controller to Run load_notification_event". Configure Pipeline Manager to check thresholds. See "Configuring Pipeline Manager to Perform Threshold Checking".
This command creates an editable XML file named bus_params_multi_ bal.xml.out in your working directory. If you do not want this file in your working directory, specify the path as part of the file name.
2.
9-19
enabledOffline specifies to check credit thresholds during the batch rating process. disabled specifies to skip credit threshold checking during the batch rating process and thus increase pipeline processing performance. This is the default setting.
4.
This command loads your changes into the multi_bal instance of the /config/business_params object.
Caution: BRM uses the XML in this file to overwrite the existing multi_bal instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRMs multi_bal configuration.
5. 6. 7.
Read the object with the testnap utility or Object Browser to verify that all fields are correct. Stop and restart the CM. For multiple databases, run the pin_multidb script:
pin_multidb -R CONFIG
The batch_controller.properties file connects the Batch Controller to the CM, specifies run-time parameters, identifies the batch handlers to run, and specifies when and how to run the batch handlers. The load_notification_event pin.conf file connects the load_notification_event utility to the CM. The SampleLoadHandler_config.values file specifies where the batch handler retrieves and deposits the XML files and which utility to run.
2. 3.
Connect Batch Controller to the CM, if you have not already done so. See "General Batch Controller parameters" in BRM System Administrator's Guide. Make sure the entries for the load_notification_event batch handler (BRM_ Home/apps/load_notification_event/SampleLoadUtilityHandler.pl) are correct. For example:
SampleHandler.name = SampleHandler SampleHandler.max.at.lowload.time = 1 SampleHandler.start.string = $PIN_HOME/apps/load_notification_ event/SampleLoadUtilityHandler.pl
Specify the handlers polling directory and the file pattern to look for. For example:
event1.name = eventlabel1 event1.handlers = SampleHandler event1.at = 115700 event1.file.location = $HOME/opt/ifw/data/out/notifybalancebreach/ event1.file.pattern = *.xml
Save and close the file. Connect the load_notification_event utility to the BRM database by editing the BRM_Home/apps/load_notification_event/pin.conf file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide. Open the BRM_Home/apps/load_notification_event/SampleLoadHandler_ config.values file in a text editor. Specify the directory from which to retrieve the XML files in the $STAGING entry. For example:
$STAGING = "$HOME/opt/ifw/data/out/notifybalancebreach/"
7. 8.
9.
Specify the directory in which the handler archives the output XML files that loaded successfully into BRM in the $ARCHIVE entry. For example:
$ARCHIVE = "$HANDLER_DIR/archive"
10. Specify the directory in which the handler stores the output XML files that failed
Configure the DAT_BalanceBatch module. See "DAT_BalanceBatch" in BRM System Administrator's Guide. Configure the DAT_PortalConfig module. See "DAT_PortalConfig" in BRM System Administrator's Guide.
9-21
3.
Configure the FCT_ApplyBalance module. See "FCT_ApplyBalance" in BRM System Administrator's Guide. When you configure the FCT_ApplyBalance module, you specify the following:
The maximum number of notifications in the output file. See "Configuring the maximum number of notifications". The output file prefix and directory location. See "Configuring the output XML file".
Configuring the maximum number of notifications You specify the maximum number of notification events that FCT_ApplyBalance writes into the XML output file by using the NumberOfNotificationLimit registry entry. When the file breaches the maximum number, FCT_ApplyBalance closes the file and begins writing notification events into a new XML output file.
Note:
You can identify the order in which XML output files were created by the sequence number used in the file name. See "About the Format of the XML Output File Name".
Configuring the output XML file After FCT_ApplyBalance identifies that an EDR caused a balance to breach a credit threshold, it writes the EDR to an output XML file. You can specify the prefix for the output file name by using the OutputPrefix registry entry and the directory in which to save the file by using the OutputDirectory registry entry.
To set both the credit limit and the resource consumption rules, use the PCM_OP_ BILL_SET_LIMIT_AND_CR opcode. See "How BRM Handles Consumption Rules and Credit Limits". To customize setting the credit limit, use the PCM_OP_CUST_POL_PREP_LIMIT policy opcode and the PCM_OP_CUST_POL_VALID_LIMIT policy opcode. See About the PREP and VALID opcodes.
The opcode sets the consumption rule and credit limit in a balance group for both currency and non-currency resources. This opcode must be called separately for each resource to be set. PCM_OP_BILL_SET_LIMIT_AND_CR creates a new /event/billing/limit event each time a credit limit is changed and a new /event/billing/consumption_rule event each time a consumption rule is changed. By default, PCM_OP_BILL_SET_LIMIT_AND_CR sets or changes the credit limit and consumption rule in the account-level /balance_group object. To set a credit limit and consumption rule for any of the other billing entities associated with the object, specify them with the optional PIN_FLD_BAL_GRP_OBJ input flist field. The credit limit is passed in the PIN_FLD_LIMIT array of the PCM_OP_BILL_SET_ LIMIT_AND_CR input flist, which contains the resource ID of the sub-balance to change or create. The credit limit is set in the PIN_FLD_BALANCES array of the /balance_group object of the various billing entities. The POID of this object is passed in the PIN_FLD_BAL_GRP_OBJ field of the input flist. The consumption rule is passed in the PIN_FLD_RULES array of the PCM_OP_BILL_ SET_LIMIT_AND_CR input flist, which contains the resource ID of the sub-balance to change or create. The consumption rule is set in the PIN_FLD_CONSUMPTION_ RULE field of the /balance_group object of the various billing entities. A non-currency resource without an explicitly set credit limit has a default credit limit of zero. If PCM_OP_BILL_SET_LIMIT_AND_CR is called for a non-existent resource, the resource is created. In the specified balance group, the resource is created, the credit limit is set, and the current balance is set to zero. PCM_OP_BILL_SET_LIMIT_AND_CR does not affect the current balances of the account. To return all the fields in the event object, set the PCM_OPFLG_READ_RESULT flag. If this flag is not set, PCM_OP_BILL_SET_LIMIT_AND_CR returns only the POID. To run PCM_OP_BILL_SET_LIMIT_AND_CR 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 that would have been used to create the event object are returned to the caller. If the flag is not set, either the /event/billing/limit object or the /event/billing/consumption_rule object is created to record details of the operation.
9-23
Taxware must validate the VAT certificate number when you enter it. You must have the Taxware Data Manager (DM) running when you enter VAT certificates, and the tax_valid entry in the CM pin.conf file must be set to 1. If you do not, the validation result will fail.
10
10
This chapter explains how to manage Oracle Communications Billing and Revenue Management (BRM) business profiles.
A set of requirements that a bill unit (/billinfo object) and its related objects must meet to be associated with the profile. These requirements are stored in validation templates linked to the business profile. You can create validation templates for the following objects: /account /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
An array of key-value pairs used to retrieve information about the bill units that belong to the business profile. For example, a business profile object that includes the key Prepaid with the value Yes indicates that bill units belonging to the business profile are prepaid. A business profile set up for postpaid bill units includes the key Postpaid with the value Yes. To find out whether a bill unit is associated with a prepaid or postpaid bill, you check the value of this key in the
bill units business profile. See "Getting Information about an Objects Business Profile". To create business profiles, see "Setting Up Business Profiles and Validation Templates".
Note:
Customer Center does not support business profiles. You can, however, create a custom user interface (UI) that does the following: Enables customer service representatives (CSRs) to assign bill units to business profiles. Provides different interfaces based on the business profile of a bill unit. <nxt_stmnt> For information about setting up business profiles and assigning bill units to them, see "Managing Business Profiles".
A set of iScript rules that determine whether a bill unit and its related objects meet the requirements of the business profile with which the template is associated. See "About Using iScripts to Validate Objects for Business Profiles". An array of key-value pairs used to retrieve information about the bill units that belong to the business profiles to which the validation template is linked. For example, if a service template linked to a business profile includes the key IsServiceGold with the value Yes, that indicates that bill units belonging to the business profile are associated with a premium (Gold) service. To find out whether a bill unit is associated with a Gold service, you check the value of this key in the templates linked to the bill units business profile. See "Getting Information about an Objects Business Profile".
Note:
Key-value pairs are not used in the validation process that determines whether a bill unit, balance group, or service object meets the requirements of a business profile.
A business profile can be associated with the validation templates listed below in Table 101:
Table 101 Validation Templates for Business Profiles Description Contains the rules used to validate every /billinfo object associated with the business profile. Only one bill unit validation template can be associated with a business profile.
Table 101 (Cont.) Validation Templates for Business Profiles Validation template Balance group validation template (/config/template/balance_ group object) Group validation template /config/template/group Resource sharing group validation template Description Contains the rules used to validate every /balance_group object associated with the business profile. Only one balance group validation template can be associated with a business profile. Contains the rules used to validate every /group object associated with the business profile. Only one group validation template can be associated with a business profile.
Contains the rules used to validate every charge sharing, discount sharing, or profile sharing group associated with the business profile. Only one resource sharing group (/config/template/group/sharin template can be associated with a business profile. g/* objects) Ordered balance group validation template (/config/template/ordered_ balgrp object) Profile validation template (/config/template/profile object) Purchased discount validation template (/config/template/purchased_ discount object) Purchased product validation template (/config/template/purchased/p roduct object) Service validation templates (/config/template/service/* objects) Contains the rules used to validate every ordered_balgrp object associated with the business profile. Only one ordered balance group template can be associated with a business profile. Contains the rules used to validate every /profile/acct_ extrating object or /profile/serv_extrating object associated with the business profile. Only one profile template can be associated with a business profile. Contains the rules used to validate every /purchased_ discount object associated with the business profile. Only one resource sharing group template can be associated with a business profile. Contains the rules used to validate every /purchased_ product object associated with the business profile. Only one resource sharing group template can be associated with a business profile. Service objects are validated against the rules in the service template that most closely matches their service type. A business profile can be associated with only one template per base service (/service) and service type (/service/*). For example, if a business profile is associated with a /config/template/service template and a /config/template/service/telco/gsm template, /service/ip objects are validated against the former template and /service/telco/gsm/data objects are validated against the latter template.
If a business profile is not associated with a validation template for a particular type of object, objects of that type are not validated because they do not have to meet any requirements to belong to the business profile. To create validation templates, see "Setting Up Business Profiles and Validation Templates". For information about triggering business profile validation, see "About Using iScripts to Validate Objects for Business Profiles".
The iScript validation mechanism is triggered for a bill unit and all of its related objects whenever any of the following actions takes place:
You assign a bill unit to a business group. You modify a bill unit that belongs to a business group. You create or modify an object related to a bill unit that belongs to a business group. For a list of valid objects, see "About Business Profiles".
BRM does not supply iScript validation rules because customer requirements vary. Instead, you must create custom rules to meet your business needs. For information about creating iScript validation rules, see "Creating iScripts and iRules" in BRM Developer's Guide. For information about adding the rules to validation templates, see "Defining Validation Templates".
Open the pin_business_profile.xml file in an XML editor or a text editor. By default, the file is in the BRM_Home/sys/data/config directory.
2. 3. 4.
Enter the appropriate information into the file. See "Editing the Business Profile Configuration File". Save and close the file. Use this command to load pin_business_profile.xml file:
load_pin_business_profile pin_business_profile.xml
Important:
When you run the utility, the pin_business_profile.xml and business_configuration.xsd files must be in the same directory. By default, both files are in BRM_Home/sys/data/config. See "Validating Your Business Profile Configuration File Edits". This utility needs a configuration (pin.conf) file in the directory from which you run the utility. If you do not run the utility from the directory in which pin_ business_profile.xml is located, include the complete path to the file. For example:
5. 6.
Open the localization file BRM_Home/sys/msgs/businessprofiles/business_ profile_descr.locale in an XML editor or text editor. Update the file with the changes you made to the pin_business_profile.xml file. Include the localized business profile name, description, and business profile ID number. For example:
DOMAIN = "Business profiles" ; STR ID = 1 ; VERSION = 1 ; STRING = "Convergent" ; END STR ID = 2 ; VERSION = 1 ; STRING = "Convergent Business Profile Description" ; END
7. 8. 9.
Save and close the file. Load the localized strings into BRM. See "Loading Localized or Customized Strings" in BRM Developer's Guide. To verify that the business profile and validation template information was loaded, display the /config/business_profile objects and /config/template subclass objects by using one of the following features:
For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
BRM_Home/sys/data/config/pin_business_profile.xml file. This file contains prepaid, postpaid, and convergent business profiles by default. To edit this configuration file, open it in an XML editor or text editor and then perform these tasks:
Defining Business Profiles Modifying Business Profiles Deleting Business Profiles Defining Validation Templates Modifying Validation Templates Deleting Validation Templates
The name of the business profile ("BusinessProfile name"). A description of the business profile ("Desc"). A list of associated validation templates ("TemplateId" elements). For information about how many validation templates can be associated with a business profile, see "About Validation Templates". A list of key-value pairs ("NameValue" elements). An unlimited number of key-value pairs can be associated with a business profile. See "About Business Profiles". An optional attribute ("type"). If the type attribute value is Invoice, the business profile is identified as an invoicing business profile. See "Specifying BI Publisher Invoice Report and Template Names in BRM" in BRM System Administrator's Guide.
To create a business profile, add a BusinessProfile child element to the BusinessProfileList parent element. In the child element, specify values for the items listed in Table 102:
Table 102
Business Profile Elements Description Character string used as the name of the business profile object (for example, PrepaidGold). Possible values The name must be unique within your BRM system. Minimum length is 1 character. Maximum length is 255 characters. Note: This string is mapped to the PIN_ FLD_NAME field in the /config/business_ profile object. Values in this field can be used to populate a list of business profiles in a user interface (UI). When creating the string, take any UI length restrictions into consideration.
type
An optional attribute that identifies a business profile. Character string that describes the type of bill units that belong to the business profile (for example, Bill units with credit balances).
Invoice
Desc
Minimum length is 1 character. Maximum length is 255 characters. Note: This string is mapped to the PIN_ FLD_DESCR field in the /config/business_ profile object. Values in this field can be used to populate a list of business profile descriptions in a UI. When creating the string, take any UI length restrictions into consideration. See "Template name" and "Template type".
TemplateId
ID of a validation template associated with the business profile. In each TemplateId element, specify the following:
The name value of a validation template defined in the files TemplateList element. The type value of the same template.
Table 102 (Cont.) Business Profile Elements XML element or attribute NameValue Description Key-value pair used to retrieve information about objects associated with the business profile. In each NameValue element, specify the following:
Possible values Minimum length of each character string is 1 character. Maximum length of each character string is 255 characters.
key: Character string used with NameValue value to describe characteristics of the bill units belonging to the business profile (for example, IsSponsor). value: Character string used with NameValue key to describe characteristics of the bill units belonging to the business profile (for example, Yes and No).
Important:
You cannot delete a business profile to which any bill unit belongs.
When you load the contents of the configuration file into your BRM database (see "Setting Up Business Profiles and Validation Templates"), BRM deletes the specified business profile.
The name of the validation template ("Template name"). The type of object validated by the templates rules ("Template type"). A description of the validation template ("Desc"). The rules used to validate objects governed by the template ("Iscript"). A list of key-value pairs ("NameValue" elements). An unlimited number of key-value pairs can be associated with a validation template. See "About Validation Templates".
To create a validation template, add a Template child element to the TemplateList parent element. In the child element, specify values for the items listed in Table 103:
Table 103 Template Elements and Values Description Character string used as the name of the validation template object (for example, Prepaid balance group). Possible values Minimum length is 1 character. Maximum length is 255 characters. Note: This string is mapped to the PIN_ FLD_NAME field in /config/template subclass objects. Values in this field can be used to populate a list of validation templates in a UI. When creating the string, take any UI length restrictions into consideration.
Table 103 (Cont.) Template Elements and Values XML element or attribute Template type Description The type of object the template validates. Possible values Can be any of the following object types:
/balance_group /billinfo /group/sharing /group/sharing/* /ordered_balgrp /profile /profile/* /purchased_discount /purchased_product /service /service/*
Desc
Character string that describes characteristics of the objects governed by the template (for example, Balance group for bill units with credit balances).
Minimum length is 1 character. Maximum length is 255 characters. Note: This string is mapped to the PIN_ FLD_DESCR field in /config/template subclass objects. Values in this field can be used to populate a list of validation template descriptions in a UI. When creating the string, take any UI length restrictions into consideration. See "Using iScripts in Validation Templates". Minimum length is 1 character. Maximum length is 255 characters.
Iscript
Set of iScript rules used to validate objects governed by the template. Key-value pair used to retrieve information about objects associated with the validation template. In each NameValue element, specify the following:
NameValue
key: Character string used with NameValue value to describe characteristics of the bill units associated with the validation template (for example, IsServiceGold). value: Character string used with NameValue key to describe characteristics of the bill units associated with the validation template (for example, Yes and No).
Important:
When you load the contents of the configuration file into your BRM database (see "Setting Up Business Profiles and Validation Templates"), BRM deletes the specified validation template.
For more information about the XSD reference file, see "About Validating XML Configuration Files" in BRM System Administrator's Guide. After validating the XML contents against the schema definition, the utility converts the XML file into an flist. From the flists template array, the utility compiles the iScript rules. If any syntax errors occur, the load operation fails.
Call the PCM_OP_CUST_COMMIT_CUSTOMER opcode. In the opcodes input flist, specify the /config/business_profile objects POID in the PIN_FLD_BUSINESS_PROFILE_OBJ field of the appropriate BILLINFO array element.
2. 3.
PCM_OP_CUST_COMMIT_CUSTOMER passes the business profile information to the PCM_OP_CUST_CREATE_ACCT opcode. PCM_OP_CUST_CREATE_ACCOUNT calls the following opcodes to validate the /billinfo object and its balance groups and services against the rules in the validation templates associated with the business profile:
The PCM_OP_CUST_SET_BILLINFO opcode, which validates the /billinfo object against the bill unit validation template (/config/template/billinfo object) and sets the /billinfo objects PIN_FLD_OBJECT_CACHE_TYPE value. The PCM_OP_CUST_SET_BAL_GRP opcode, which validates the balance group objects against the balance group validation template (/config/template/balance_group object) and sets the /balance_group objects 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 objects 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 (see "About Validation Templates" for details). 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.
If no validation errors occur, PCM_OP_CUST_CREATE_ACCOUNT 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.
To assign a bill unit to a business profile after account creation, see "Changing a Bill Units Business Profile".
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.
To change a bill units business profile, call the PCM_OP_CUST_CHANGE_ BUSINESS_PROFILE opcode and include the following information in its 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.
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:
a. b.
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. If cache residency distinction is enabled, changes the /account objects 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-level /purchased_ product objects.
Creates a list of all the objects associated with the bill unit. 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. 5.
After validating a balance group, creates a list of all the services associated with the balance group. 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). For each service in the list, checks whether the input flist contains a requested modification. If a modification is requested, calls the PCM_OP_CUST_MODIFY_SERVICE opcode to make the modifications and to validate the modified service object
6.
10-13
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 (see "About Validation Templates" for details). 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.
For information on cache residency, see "Configuring BRM for Cache Residency Distinction" in BRM System Administrator's Guide.
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 keys 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/*
For more information about key-value pairs, see "About Business Profiles" and "About Validation Templates".
10-15
11
11
This chapter describes how to manage customers services and products; for example, adding Oracle Communications Billing and Revenue Management (BRM) services, giving discounts, and transitioning deals and plans. For information about creating products, deals, and plans, see "About Creating a Price List" in BRM Setting Up Pricing and Rating. For information about creating services, see "Adding Support for a New Service" in BRM Developer's Guide.
Managing Services
A service is a capability that you provide to customers, such as telephony, Internet access, or email. You add services to an account by purchasing plans and deals. You can also change the service status and change how the services are provisioned; for example, add mail boxes to an email account.
Managing Services
If the deal is required, PIN_FLD_TYPE is set to PIN_BILL_SERVICE_REQUIRED. If the deal is optional, PIN_FLD_TYPE is set to PIN_BILL_SERVICE_OPTIONAL.
When the PCM_OP_CUST_CREATE_CUSTOMER opcode creates the services in an account, it first validates whether the deal dependency functionality is enabled in the CM pin.conf file. If so, it sets the services PIN_FLD_TYPE value accordingly.
You cannot activate an optional service that has been closed if the required service is closed. When you transition a deal or plan in Customer Center, the service associated with the old deal is closed, and its status flag value is set to PIN_STATUS_FLAG_DUE_TO_TRANSITION. You cannot change the status of a service with this status flag value.
When a service is active, the customer can use the service. When a service is closed or inactive, the customer cannot use the service.
Managing Services
You can specify a date in the future on which the service status will change. For information on changing account and service status, see "Changing Account and Service Status". You can edit the list of reasons why a service was activated or inactivated. See "Customizing the List of Reasons for Account Changes".
Specifying how to authorize service usage. By default, a customer is not authorized to use a service if a credit limit has been reached. Inactivating services. When a service is inactivated, the customer cannot use it. Inactivating accounts. When an account is inactivated, no services in the customers account can be used by the customer. Canceling products. When an accounts product is canceled, the associated service cannot be used.
For information on setting the account status, see "Changing Account and Service Status". In addition to capturing usage information, BRM can also send information to the system that controls the service. For example, BRM can notify an IP gateway that a customers credit limit has been reached and the call should be terminated.
To publish a service order, use the PCM_OP_PROV_PUBLISH_SVC_ORDER opcode. This opcode sends an /event/provisioning/service_order/eventtype event to the Provisioning Data Manager (DM), where eventtype is the type of event. This opcode takes as input the Portal object ID (POID) of the service order event and a substruct containing the service order information that should be sent to the Provisioning DM.
To update a service order, use the PCM_OP_PROV_UPDATE_SVC_ORDER opcode. This opcode updates the status of an /event/provisioning/service_order/* event. An /event/provisioning/service_order/* event stores the service order and information such as the status, service order type, and actions required. When a response is received from a provisioning platform, PCM_OP_PROV_ UPDATE_SVC_ORDER uses information in the input flist to update the status of an /event/provisioning/service_order/* event.
Managing Products
PCM_OP_PROV_UPDATE_SVC_ORDER receives as input the POID of the service order, the service order status, and other service order information.
To validate and modify parameters for updating service orders, use the PCM_OP_ PROV_POL_UPDATE_SVC_ORDER policy opcode. This policy opcode is called by PCM_OP_PROV_UPDATE_SVC_ORDER when a response is received from a provisioning system. By default, the PCM_OP_PROV_POL_UPDATE_SVC_ORDER policy opcode validates and transforms a global system for mobile communications (GSM) service order. When a response is received from a provisioning system, this policy opcode maps the response parameters to corresponding fields in the /event/provisioning/service_order/telco/gsm object. The input flist to the PCM_OP_PROV_POL_UPDATE_SVC_ORDER policy opcode includes the complete response from the provisioning applications. Based on the type of the service order, you can modify or validate the response flist. By default, the PCM_OP_PROV_POL_UPDATE_SVC_ORDER policy opcode returns the input flist without any change, except in the case of GSM services where the input flist is validated and the format is modified to map the fields in the event/provisioning/service_order/telco/gsm object.
Managing Products
A product is a pricing object that defines how to charge your customer for goods and services. A product consists of one or more rate plans that specify the cost of each billable event that affects a customers account. You use Customer Center to display each product that the account owns and the basic information about each product, including the products service, purchase date, and status.
Purchasing Products
Although you can manage products individually, you do not purchase individual products for a customer; instead, you purchase a deal in Customer Center that contains the product. See "Purchasing Deals". Functionally speaking, the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL opcode calls the PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT opcode to purchase the products a deal contains.
Managing Products
If the system is configured for time stamp rounding, PCM_OP_SUBSCRIPTION_ PURCHASE_PRODUCT rounds the start and end times to 00:00:00 hours.
If start and end dates are not aligned with the accounting cycle, the start date is set to February 20. If start and end dates are aligned with the accounting cycle, the start date is set to February 5 if the accounting cycle is short or March 5 if the accounting cycle is long.
Note:
If the purchase, cycle, or usage start and end time is modified in Customer Center while purchasing the deal or creating the account, any delay specified in Pricing Center is ignored.
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT does not apply either deferred purchase or cycle forward fees. These fees are applied when the pin_ cycle_fees utility is run as part of the pin_bill_day billing script. See "Applying Deferred Product Purchase Fees". If the product has a purchase fee and if the purchase start time is not deferred, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT applies the purchase fee and creates the associated /event/billing/product/fee/purchase object.
Note:
Unlike flexible cycle forward events, BRM does not support custom events for purchase fee events. Purchase fees associated with a product are stored in /event/billing/product/fee/purchase object.
If the product has a cycle forward fee and if the cycle start time is not deferred, PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT applies the cycle forward fee by calling the necessary opcodes. This creates the /event/billing/product/fee/cycle/cycle_forward_feetype object, where feetype is the type of cycle forward fee. If the product is purchased as part of a deal transition, PCM_OP_SUBSCRIPTION_ PURCHASE_PRODUCT can waive the purchase fees based on the PIN_FLD_
Managing Products
FLAGS value passed in by the PCM_OP_SUBSCRIPTION_TRANSITION_DEAL opcode. For more information, see "How Deals are Transitioned".
When PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT is called during product customization, the value of PIN_FLD_FEE_FLAG in the input flist determines whether cycle and purchase fees are applied: Cycle and purchase fees. If PIN_FLD_FEE_FLAG is set to PIN_BOOLEAN_ FALSE, cycle and purchase fees are not applied. Purchase fees. If PIN_FLD_FEE_FLAG is set to PIN_BOOLEAN_TRUE, the opcode applies purchase fees. The opcode uses the purchase fee of the product (base or customized) that is valid at purchase time. Purchase fees are not applied for customized products created after the initial product purchase. Cycle fees. If PIN_FLD_FEE_FLAG is set to PIN_BOOLEAN_TRUE, the opcode calls the appropriate opcode to calculate and apply cycle fees. Cycle fees are applied based on the validity of the base and customized products. See "Validity periods and cycle fees for customized products".
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL sets the value of PIN_FLD_FEE_ FLAG during deal purchase. See "How Deals are Purchased".
After the purchase fees are applied to the account, an /event/billing/purchase_fee object is created for auditing purposes. If the purchase fee is applied successfully, PCM_OP_SUBSCRIPTION_PURCHASE_ FEES returns the POIDs of the /account object and the /event/billing/purchase_fee object.
Managing Products
before charging the account. When the account is made active, the customer is charged. When you purchase a product for inactive or closed accounts, the products status also needs to be inactive. If the products status is active, rating modules rate and apply charges for the product. If you do not want charges to be applied, change the products status to inactive at the time of purchase or use Pricing Center to set the products status to inactive in the deal. When the account is activated, change the products status to active for charges to be applied. To enable product purchases from closed or inactive accounts:
1. 2.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). In the fm_bill section, add the following entry: fm_bill deal_purchase_for_closed_account
3. 4. 5.
Set the value of the entry to 1. Save and close the file. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Do not call PCM_OP_SUBSCRIPTION_PURCHASE_ PRODUCT directly. This opcode is always called by PCM_OP_ SUBSCRIPTION_PURCHASE_DEAL.
PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT is called to purchase products for the account or service object specified in the input flist.
Note:
If a /service object is specified, the product is purchased for that service and is a service-level product. The /service object must belong to the account. If the /service object is NULL, the product is purchased for the /account object and is an account-level deal.
If billing is due, triggers billing. Opens a transaction. Retrieves the products package ID, name, and type, which are passed in the input flist, and opens a deal instance. For information about how a deal is generated, see PCM_OP_SUBSCRIPTION_PURCHASE_DEAL. Validates that the product is available for purchase. A product is not available for purchase when any of the following apply:
4.
The products validity period has not yet started (the PURCHASE_START_T value is greater than the current time).
Managing Products
The products validity period has already ended (the PURCHASE_END_T value is less than or equal to the current time). The cycle or usage start time is less than the purchase start time. The cycle or usage end time is greater than the purchase end time. There is a PIN_FLD_PERMITTED field for the product but the POID type is not explicitly permitted. The purchase quantity is 0 or is not passed. The purchase quantity is less than the minimum purchase quantity set in your price list. The purchase quantity is greater than the maximum purchase quantity set in your price list. An attempt is made to purchase a partial quantity. The total quantity purchased for this product exceeds the maximum ownership quantity in your price list for this account or service. This applies only to subscription products that have a maximum ownership quantity specified. The total quantity purchased for this product is less than the minimum ownership quantity in your price list for this account or service. This applies only to subscription products that have a minimum ownership quantity specified.
5.
The date to which the product purchase is backdated is not prior to the G/L posting date. The date to which the product purchase is backdated is not prior to the effective date of the account or service. The date to which the product purchase is backdated is not prior to the date of the last status change of the account or service.
If the purchase product provisioning tag is set for the product, calls the PCM_OP_ SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING opcode. See "Customizing Provisioning when a Product is Purchased". If a /config/provisioning_tag object is associated with the product, this opcode runs the opcodes specified in that object to run at product purchase time. The opcode always runs the opcodes specified by the __DEFAULT__ provisioning tag. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.
7. 8. 9.
If the product is sponsored, sets PIN_FLD_SPONSOR_OBJ accordingly. If the opcode is called for a customized product, adds the POID of the base products /purchased_product object to the PIN_FLD_OVERRIDDEN_OBJ field. Determines the various start and end dates for the product. See "Handling Purchase, Cycle, and Usage Start and End Times". customized product falls within the validity period of the base product:
10. If called during advanced customization, verifies that the validity period of the
The purchase start and end times of the customized product must fall within the purchase start and end times of the base product.
Managing Products
The purchase start and end times must not overlap with the purchase start and end times of any other customized product for the same base product. The usage start and end times of the customized product must fall within the usage start and end times of the base product. The cycle start and end times of the customized product must fall within the cycle start and end times of the base product.
11. Verifies the product purchase with the specified account. 12. Applies the product to the account:
If it is a subscription product, generates a /purchased_product object with a pointer to the /account object. If it is an item product, creates an audit record for the /au_purchased_product object.
Note:
Item products cannot be deferred. The audit object is used for rerating events.
13. Sets the purchase, cycle, and usage discounts, if applicable. 14. Sets the product status in /purchased_product. 15. Checks the PIN_FLD_FLAGS value set by PCM_OP_SUBSCRIPTION_
TRANSITION_DEAL to determine whether the product purchase is due to a deal or plan transition. If so, sets the value to PIN_TRANS_WAIVE_PURCHASE_FEES.
16. Applies the appropriate purchase and cycle fees to the balance. See "Applying
the product is added to the account and all applicable fees are applied.
19. Closes the transaction.
If the product purchase is successful, PCM_OP_SUBSCRIPTION_PURCHASE_ PRODUCT returns a confirmation message. During a deal or plan transition, additional validations are performed that may prevent a successful purchase:
If the service contains at least one required deal, the service flag is set to Required. If all deals for the service are optional, the service flag is set to Optional. A required service cannot be canceled; therefore, the purchase portion of the transition does not occur. If the system flag validate_deal_dependencies is 1, BRM checks to see if there are prerequisites or if the deals are mutually exclusive before PCM_OP_ SUBSCRIPTION_PURCHASE_DEAL is called. If the permitted field in the plan is service_type, the flag is set to PBS.
Modifying Products
You use Customer Center to modify products in the following ways:
Managing Products
You can also customize the pricing of a product. See "Customizing Product Pricing". You can modify products at the following times:
You cannot inactivate a product after it has been purchased. However, you can inactivate a service. See "Activating and Inactivating Services".
You might want to delay a product purchase if the product depends on additional software or hardware setup that the customer has to wait for.
Managing Products
Changing the Purchase, Usage, and Cycle Start and End Times
The PCM_OP_SUBSCRIPTION_SET_PRODINFO opcode is called to change the purchase, cycle, or usage start and end times of an accounts purchased product. This opcode is called by the PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS opcode when the status of an accounts product is changed. After a product is purchased and its start and end dates have been set, you can change the start time to specify only another absolute date, and you can change the end time to specify only another absolute date or to end never.
Note:
If a product has been tailored to include one or more advanced customizations, be sure to consider the validity periods of the base product and all customized products when changing a validity period: The validity period of customized products must fall within the validity period of the base product, and customized products in the same deal cannot have overlapping validity periods. If these rules are not followed, PCM_OP_SUBSCRIPTION_SET_PRODINFO will not commit the product to the database.
To change the purchase, cycle, or usage validity period, specify the new start and end dates in their respective START_T and END_T fields in the PIN_FLD_PRODUCTS array in the input flist. If you change the purchase, cycle, or usage start time from first usage to an absolute date, PCM_OP_SUBSCRIPTION_SET_PRODINFO generates an event that causes Pipeline Manager to update the validity period in the pipeline database. The start and end dates are stored in the accounts /purchased_product object. If your system is configured to round time stamps, and if you modify the purchase, usage, or cycle start and end times, PCM_OP_SUBSCRIPTION_SET_PRODINFO rounds the new times to 00:00:00 hours. PCM_OP_SUBSCRIPTION_SET_PRODINFO changes the cycle and usage end times to the new purchase end time in the following cases:
You pass a new purchase end time and you do not pass a new cycle end time and usage end time. You pass 0 as the cycle end time and usage end time. The new cycle end time or usage end time is later than the new purchase end time.
BRM does not allow you to change a products purchase, usage, and cycle start and end dates as follows:
The product purchase start date if the purchase start date has elapsed. For example, on January 1, a product is purchased with the purchase start date set to January 15. On January 10, you can backdate the purchase start date to January 5. But, you cannot backdate the purchase start date on January 16; that is, you cannot backdate the purchase date when the January 15 date has passed.
The product cycle start date if the cycle start date has elapsed. The product purchase, usage, and cycle end date prior to the respective purchase start date. The product purchase, usage, cycle start or end dates prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date".
11-11
Managing Products
If you change the cycle start time from a future time to the current time, applies the cycle forward fee for the current time through the end of the current cycle. If you change the cycle end time to an earlier time and the cycle forward fee is already applied for that cycle, refunds the cycle forward fee for the unused portion of the cycle. If you change the cycle end time to a later time and the cycle forward fee is already applied for that cycle, applies the cycle forward fee for the end of the old cycle end time through the end of the new cycle.
Refunds for cycle arrears fees are not supported. Use caution when changing cycle end times. Changing the cycle end time for a cycle arrears fee has some limitations. See "Cycle Arrears Product Limitations".
If the product has a cycle arrears fee, the PCM_OP_SUBSCRIPTION_CYCLE_ ARREARS opcode is called to perform the following actions:
If you change the cycle end time from a future time to the current time, the cycle arrears fee is applied for the cycle. If you change the cycle end time from a future time to an earlier time, but later than the current time, the cycle arrears fee is not applied. However, the cycle arrears fee is applied during the next billing run.
If you change the cycle end time only once in a cycle, the cycle fee is applied either the day of the change or the next billing day, depending on the new cycle end value. If the new PIN_FLD_CYCLE_END_T value is the same as the event time, the cycle arrears fee is charged at the same time; otherwise, its charged at the next billing time.
Note:
If you use time stamp rounding, the cycle end time is compared to the event date. Otherwise, the cycle end time is compared to the event time (the current time).
Managing Products
If you change the cycle end date more than once in a cycle: If the cycle arrears fee from the first change has not yet been applied, it will not apply after the second change is made. If the new cycle end date is changed to 0 (never) or to a date later than the end of the current accounting cycle, cycle fees apply accordingly, depending on which of the following cancellation settings you specified when setting up proration for your pricing plan: Charge full: Applies no cycle fees for the whole cycle. Based on usage and is proratable: Applies cycle fees from the new cycle end date to the end of the cycle. No Charge and proratable: Applies cycle fees from the new cycle end date to the end of the cycle. No Charge and is not proratable: Applies full cycle fees.
If billing is due, triggers billing. Opens a transaction. Verifies the validity periods of customized products. See "About Customized Product Validity". For backdating operations, validates and sets the products purchase, cycle, or usage start and end dates to a backdated date. See "About backdated purchase, usage, or cycle end dates". Modifies the product information as specified. For information on how PCM_OP_ SUBSCRIPTION_SET_PRODINFO handles start and end dates, see "Changing the Purchase, Usage, and Cycle Start and End Times". Creates an audit record object (/au_purchased_product) used for rerating events. Applies the product changes to the product object (/purchased_product) owned by the account. Calculates and applies appropriate cycle fees for the event to the balance and, if necessary, calls other opcodes to record the cycle events. See "Calculating the Cycle Forward Fee". Creates the /event/billing/product/action/modify event objects.
5.
6. 7. 8.
9.
If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_SUBSCRIPTION_SET_ PRODINFO returns the entire event flist for the events created as a result of the modification. Otherwise, it returns the event POID of all event objects created as a result of the modification. An error occurs in the following cases:
If an attempt is made to change the cycle start date to a date earlier than any period for which cycle forward or arrears fees have already been applied.
11-13
Managing Products
If an attempt is made to change the cycle end date to a date before the current time but after the end of any period for which cycle forward or cycle arrears fees have already been applied.
PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING. See "Customizing Provisioning when a Product is Purchased". PCM_OP_SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS. See "Getting a List of Provisioning Tags". PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING. See "Customizing Provisioning when Canceling a Product".
Note:
The BRM provisioning tag framework is the preferred method of customizing provisioning when a product is purchased or canceled. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.
If a /service object is associated with a provisioning tag in the input flist, provisioning is invoked. If provisioning is invoked, it checks the tag table for the corresponding provisioning tag and executes the corresponding function call that modifies the appropriate fields in the /service object.
Changing the services, tags, and functions in the provisioning_tags array. Adding to or modifying the provisioning sub-functions in the fm_subscription_ pol_provisioning.c file. Using Pricing Center to modify products associated with services by including the applicable provisioning tag.
Managing Products
Important:
Each service in the provisioning_tags array is associated with a provisioning tag and a function. The provisioning tag specifies the type of service, and the function determines what is to be done with that service. For example, the PCM_OP_ SUBSCRIPTION_POL_GET_PROD_PROVISIONING_TAGS policy opcode is called by Pricing Center to access the tag table and display the list of service types and their corresponding provisioning tags. You can customize the provisioning functionality by:
Changing the services, tags, and functions in the provisioning_tags array. Adding to or modifying the provisioning sub-functions in the fm_subscription_ pol_provisioning.c file. Using Pricing Center to modify products associated with services by including the applicable provisioning tag.
If a /service object is associated with a provisioning tag in the input flist, provisioning is invoked. If provisioning is invoked, it checks the tag table for the corresponding provisioning tag and executes the corresponding function call that clears the appropriate fields in the /service object.
Upgrading Products
You can upgrade a customers product by canceling the existing product and adding the upgraded product. For example, a customer can upgrade from a limited number of hours of Internet access to unlimited access.
Tip: If your price list includes an upgrade path from limited hours to unlimited hours, you should include a rate plan in the upgrade product that removes free hours. That way, when a customer upgrades from limited hours to unlimited hours, the balance no longer includes free hours.
You can also upgrade products by including them in deals that you transition. For more information, see "Transitioning Deals".
11-15
Managing Products
Canceling Products
You can cancel a customers products by using the Plans tab Actions menu in Customer Center. You can cancel individual products or cancel all products in a deal at one time by canceling the deal; for example, to upgrade a customer to a new plan or service. See "Canceling Deals". You can cancel a product immediately or backdate the cancellation to a date earlier than the current date. You can also set the cancellation to a future date. See "Setting Start and End Dates". You can charge for product cancellations by creating a cancel rate for the product. See "How BRM Cancels Base and Customized Products" for information about canceling products that have been customized.
Note:
In Customer Center, canceled products do not show up in the Product table by default. To display them, choose Actions Customize Product Table on the Product tab. In the case of deferred product cancellation, the cancellation is applied when the pin_bill_day billing script is run. If the product is contained in a required deal, you must either transition the plan containing the required deal or close the service to cancel the product. See "About Plan Transitions in BRM".
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the cancel_tolerance entry.
Managing Products
Save and close the file. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Canceling a Product
You can cancel a product immediately or backdate the cancellation to a date earlier than the current date. You can also cancel a product in the future by modifying the product end times. You use Customer Center to cancel products.
Note: Deferred cancellation is available only for the entire quantity of the product in the account.
You must install BRM 7.5 Patch Set 1 or later to use this business parameter.
To configure BRM to include event adjustments in product cancellation refunds, modify the EventAdjustmentsDuringCancellation parameter in the subscription instance of the /config/business_params object:
When this parameter is enabled (1), BRM searches for any event adjustments associated with the product cycle fee and applies them to the refund amount. When this parameter is disabled (0), BRM does not include event adjustments when calculating product cancelation refunds.
Use the following command to create an editable XML file from the subscription instance of the /config/business_params object:
pin_bus_params -r BusParamsSubscription bus_params_subscription.xml
This command creates the XML file named bus_params_subscription.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.
2.
3.
Change 0 to 1.
11-17
Managing Products
Caution!:
BRM uses the XML in this file to overwrite the existing subscription instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRMs billing configuration.
4. 5.
Save and close the file. Use the following command to load the change into the /config/business_params object:
pin_bus_params bus_params_subscription.xml
Execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see "pin_bus_params" in BRM Developer's Guide.
6.
Read the object with the testnap utility or Object Browser to verify that all fields are correct. See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.
7. 8.
Stop and restart the CM. For multiple databases, run the pin_multidb script with the -R CONFIG parameter. For more information on this script, see "pin_multidb" in BRM System Administrator's Guide.
"About Real-Time Rate Plans" in BRM Setting Up Pricing and Rating "About Proration" in BRM Configuring and Running Billing "About Fold Events" in BRM Setting Up Pricing and Rating
For example, consider a product that grants 400 free minutes for a cycle starting on January 1 and ending on January 30. Each free minute equals one currency resource unit. On January 15, if the customer cancels the product after using 300 free minutes, the free minutes grant is prorated to 200 and the overuse of 100 free minutes is charged to the customers account by folding 100 free minutes to 100 currency resource units.
Important:
You can prorate free resources by using folds only if the relationship between the currency resource and the free resource is fixed. For example, one free minute equals one currency unit. It does not work if the conversion between the resources is based on tiered rates; for example, different rates for peak time and non-peak time.
Managing Products
Create a product for the free resource you want to offer to your customers. For example, free minutes. Define a cycle forward rate plan that adds free resources to the product in every cycle.
Important:
To rate overuse of the free resource, make sure the credit limit of the free resource is unlimited.
3. 4. 5.
Specify that the free resource is prorated based on usage when a customer cancels a product. Define a cycle fold rate plan to fold the free resource. Configure a fold to convert the free resource to the currency resource when there is overuse.
Conditional discounts are rarely used for purchase and cancellation events.
To ensure that conditional discounts are reliably calculated when canceling a product, do one of the following:
When you define a discount, select options to prorate the balance impact for the amount to ensure there is no refund at the time of product cancellation.
11-19
Managing Products
If the discount calculated at product cancellation is not correct and the customer calls to get a resolution, the CSR can manually calculate the correct discount and the prorated refund amount.
Do not delete canceled products if you use delayed billing. See "Rating Delayed Events for Canceled Products". Do not delete canceled products if you rerate events. Events that use deleted products cannot be rerated. You cannot delete a product if there are provisioning tags defined for that product. Products with provisioning tags are updated by the provisioning system and therefore must remain in the BRM database. Oracle recommends that you not delete canceled products and discounts because other external systems may also use them.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). Change the value of the keep_cancelled_products_or_discounts entry.
0 deletes the canceled /purchased_product objects. 1 (default) keeps the deleted products in the /purchased_product objects.
3. 4.
Save and close the file. Restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Closes billing if the account balance is affected. Opens a transaction. Verifies that the product is valid for cancellation.
Managing Products
4. 5.
Checks if the corresponding deal is a required deal. If so, does not perform the cancellation. Calls the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode to determine whether to cancel and delete the product, to cancel without deleting the product, or to not allow the cancellation. If the corresponding deal has any dependencies, the product cannot be deleted.
Note:
By default, BRM retains canceled products. You can change this behavior by customizing the PCM_OP_SUBSCRIPTION_POL_ SPEC_CANCEL policy opcode. See "Customizing Product Cancellation".
6.
If the cancel product provisioning tag is set for the product, PCM_OP_ SUBSCRIPTION_CANCEL_PRODUCT calls the PCM_OP_SUBSCRIPTION_POL_ CANCEL_PROD_PROVISIONING policy opcode to clear fields in the service object. See "Customizing Provisioning when Canceling a Product". If a /config/provisioning_tag object is associated with the product, this opcode runs the opcodes specified in that object to run at product cancellation time. The opcode always runs the opcodes specified by the __DEFAULT__ provisioning tag. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating.
7.
Validates the product quantity requested for cancellation. The quantity must be less than or equal to the quantity owned by the account.
Note:
When the quantity to cancel is less that the quantity owned, the product quantity is modified; the product is not canceled.
8.
The date to which the product cancellation is backdated is not prior to the G/L posting date The date to which the product cancellation is backdated is not prior to the effective date of the account or service. The date to which the product cancellation is backdated is not prior to the last status change date of the account or service.
Sets the products purchase, usage, and cycle end dates to the cancellation date. TRANSITION_DEAL to determine if cancellation fees should be waived.
10. Reads the PIN_FLD_FLAGS value passed in from PCM_OP_SUBSCRIPTION_ 11. Cancels any customized products associated with the product. 12. For products that have not been customized, applies the following fees, if
applicable:
If the product is active and has any cycle forward fee associated with it, and if the product is canceled in the middle of the cycle, the cycle forward fee is refunded for the unused portion of the cycle and an appropriate cycle forward event is generated. If the product is active and has a cycle arrears fee associated with it, and if the product is canceled in the middle of the cycle, the cycle arrears fee is charged
11-21
Managing Products
for the used portion of the cycle and an /event/billing/product/fee/cycle/cycle_arrears event object is generated.
If the product has a cancellation fee, the cancellation fee is applied and an /event/billing/product/fee/cancel event object is generated.
Note:
If the products validity period is configured to start on first usage and has not yet been set, the product has not been activated. In this case, cycle fees are not charged.
13. For products that have been customized, applies cancellation fees based on
If a customized product is currently valid, the cancellation fees in the customized product are applied. If no customized product is currently valid, the cancellation fees in the base product are applied.
refunds the cycle fees of the base product, then reapplies them based on the new validities. See "How BRM Cancels Base and Customized Products".
15. Creates the audit log /event/billing/product/action/cancel object to record the
detailed information, see the output flist specification. PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT fails in the following cases:
If the specified product in the input flist does not exactly match the /purchased_ product object. If the cancellation quantity is not passed in the input flist or is passed as 0. If the product pricing quantity is less than the cancellation quantity specified in the input flist.
BRM requires information stored in the product to rate events when you use delayed billing and when events are rerated. In these cases, products should not be deleted.
Note:
You can also delete canceled products by setting a configuration parameter. See "Specifying to Delete Canceled Products".
You can customize the behavior of the PCM_OP_SUBSCRIPTION_POL_SPEC_ CANCEL policy opcode by setting the PIN_FLD_ACTION field to one of these values:
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_ONLY, which sets the status of the /purchased_product object to Canceled and does not delete the /purchased_product object when canceled. PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_DELETE, which deletes the /purchased_product object when it is canceled. PIN_BILL_CANCEL_PRODUCT_ACTION_DONOT_CANCEL, which stops the product cancellation.
Note:
By default, the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL policy opcode reads the provisioning tag of the product object. If a provisioning tag is configured for the product, the action is set to PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_ ONLY. If there is no provisioning tag, the action is set to PIN_BILL_CANCEL_ PRODUCT_ACTION_CANCEL_DELETE.
Override the price for purchase and cycle events. See "Overriding a Product Price". Provide a fixed-amount or percentage discount that applies to the product as a whole. See "Providing Product Discounts". Modify rates or price models in the product by specifying positive or negative changes to resource balance impacts. See "Modifying Rates and Price Models in a Product".
Price overrides and product discounts are collectively called basic customizations. Modifications to rates and price models in a product are called advanced customizations.
11-23
Note:
To make purchase or cycle events free, enter 0 as the override price. If you specify both a discount and an override price, the override price is discounted. To override a price when the account uses two currencies, make sure the display currency is the accounts primary currency. Enter the override price in the primary currency.
Important:
If a product has more than one cycle forward rate, do not enter an override price in the Cycle Info group. The override price substitutes for all cycle forward rates that affect the balance of a currency resource. Overriding the price applies only to scaled balance impacts. If the product includes a fixed balance impact, the override price is added to the price, it does not replace it.
Product discounts are not the same as the separate, purchasable discounts that you can add to an account. See "About Discounts" in BRM Configuring Pipeline Rating and Discounting.
To discount a product, the CSR selects the product in the customers account and enters the discount for the appropriate type of fee. Figure 114 shows Customer Center defining a discount of $5 for the purchase fee:
Note:
To give discounts when the account has two currencies, make sure the display currency is the accounts primary currency. If you are giving a fixed-amount discount, enter the amount in the primary currency.
You can use Pricing Center to specify if products are discountable. See "Providing Discounts with Deals" in BRM Setting Up Pricing and Rating. You can provide fractional discounts up to two decimal places; for example, 10.25%, but not 10.255%. You can configure the way discount results are calculated. See "Providing Discounts with Deals" in BRM Setting Up Pricing and Rating.
11-25
specify its validity dates and percentage changes to resource impacts in rates and price models as shown below in Figure 115.
Figure 115 Customizing Products
If you do not use Customer Center as your customer relations management (CRM) tool, you can call opcodes from another CRM tool to customize products. You can modify existing customizations with opcode calls. See "Using Opcodes to Customize Products" in BRM Setting Up Pricing and Rating. You must grant permissions to Customer Center users to allow them to customize a product. You use the accounttool/product/override to control the ability to customize a product. This permission is not granted by default. You can define minimum and maximum customization limits. A product can be customized only if the deal that contains it was created with the Deal customization setting at Optional or Required.
For real-time rate plans, customized objects include event maps, rate plans, rate plan selectors, rate tiers, day and date ranges, time ranges, rates, and balance impacts. For pipeline rate plans, customized objects include rate plans, rate plan versions, rate plan configurations, price model selectors, price models, and price model steps.
Because each customized /product object includes a copy of the uncustomized data in the original base product, the customized product is isolated from changes to the base product. For example, suppose you customize one rate in a product but leave all the other rates at their original values. BRM uses the rates in the customized product, including the ones you did not change, as long as the customized product is valid. Even if the base product changes during the customized products validity period, BRM uses the original, unmodified rates along with the rate that you customized. If you want changes to a base product to be reflected in a customized product, you must cancel the customized product and create a new customization based on the modified base product. In some cases, a customized /product object may include multiple copies of a pipeline pricing component. This situation occurs because it is possible for multiple rate plan configurations and model selector rule sets to point to or customize the same price model. In this case, BRM includes a copy of the unmodified price model as well as a modified version of the same price model. For example, RatePlanConfigurationA might point to PriceModel1 in its original form whereas RatePlanConfigurationB modifies PriceModel1. The customized /product object would include a copy of the unmodified PriceModel1 as well as a copy that includes the modifications. To distinguish them from other /product objects, customized /product objects include the field PIN_FLD_TAILORMADE with a value of 1. BRM filters by this field to prevent customized products from appearing in Pricing Center. A customized /product object also includes the POID of the base product on which it is based, stored in the PIN_FLD_BASE_PRODUCT_OBJ field. BRM stores customized real-time rates in the PIN_FLD_TAILORMADE_DATA field of the /rate object. This field stores resources and the percentage change to them as semicolon-delimited, comma-separated pairs. For example, reductions of 10% to the euro and US dollar resources would be stored in PIN_FLD_TAILORMADE_DATA as EURO, -10;USD, -10. How BRM stores and updates customized pipeline data If a customized product includes changes to a pipeline rate plan, BRM stores customized pricing data in the pipeline database as well as in the /product object. In addition, when you create or modify a customized product with a pipeline rate plan, BRM generates a notification event that causes pipeline modules to refresh their data caches. When you customize a pipeline rate plan in a product, BRM creates copies of the relevant pipeline pricing components and stores them in the pipeline database. These customized pricing components are given a unique code based on the original component code. See "About customized product and pipeline pricing component names". Pipeline Manager uses the data stored in the pipeline database to initialize pipeline modules if the pipeline is restarted after the product customization occurs. When customization occurs while the pipeline is active, modules use the event notification mechanism to update their data. See "Updating pipeline modules with customized data". Table 111 lists the pipeline pricing components that can be customized along with the database tables in which they are stored:
11-27
Table 111
Pipeline Components that can be Customized Database table IFW_RATEPLAN IFW_RATEPLAN_VER IFW_RATEPLAN_CNF IFW_PRICEMODEL IFW_MODEL_SELECTOR IFW_SELECTOR_RULESET IFW_SELECTOR_RULE IFW_SELECTOR_RULE_LINK IFW_SELECTOR_DETAIL
Pricing component Rate Plan Rate Plan Version Rate Plan Configuration Price Model Model Selector Model Selector Rule Set Selector Rule Selector Rule Link Selector Detail
The database table for price models (IFW_PRICEMODEL) includes the TAILORMADE_DATA column, which stores customized resources and the percentage change to them as comma-separated pairs. For example, reductions of 10% to the euro and US dollar resources would be stored as EURO, -10;USD, -10. The TAILORMADE column in the IFW_PRICEMODEL, IFW_MODEL_SELECTOR, IFW_SELECTOR_RULE, IFW_SELECTOR_DETAIL, and IFW_SELECTOR_RULESET tables indicates whether an object is customized. A value of 1 in the column indicates a customized object. Updating pipeline modules with customized data When you create or modify a customized product, BRM generates a notification event: /event/notification/price/tailormade_products/create or /event/notification/price/tailormade_products/modify. These events include full customized product information, including pipeline rate plans, rate plan configurations, price models, and price model selectors. The DAT_PriceModel, DAT_Rateplan, and DAT_ModelSelector modules respond to these events through their connection to the DAT_Listener module. They update their caches to include the customized data so that it can be used during rating. About customized product and pipeline pricing component names BRM automatically creates the name of the customized /product object based on the name of the base product and the creation time. BRM prepends a hexadecimal version of the creation time, in seconds, to the base product name. For example, if the base product name is GSMTelephony, a customized product name could be AE9C6890_ GSMTelephony. The original product name is truncated if necessary to maintain a size limit of 255 characters. BRM also renames the copies it creates of pipeline pricing components. The code of each component is changed to include a two-letter abbreviation that indicates the component type, the hexadecimal creation time in milliseconds, and a unique five-digit integer value. These are the abbreviations for the various component types:
PR: pipeline rate plan PM: pipeline price model MS: pipeline model selector
RS: pipeline model selector rule set SR: pipeline model selector rule SD: pipeline model selector detail
You can create multiple customizations of a base product as long as their validities do not overlap. Figure 117 shows how you can customize a product to provide the subscriber with a 25% reduction on usage for March and a 10% reduction for April.
Figure 117 Multiple Discounts Defined for a Product
Note:
You can create only one customized product for a base product under these circumstances: The base product validity is configured to start on first usage. The validity of the customized product must also start on first usage. The base product validity begins on a specific date and you set the customized product to start on first usage.
After the validity start date has been reached, you can create additional customizations for the base product.
11-29
You customize during product purchase and set the starting validity periods of the base and customized products to be the same. The validity periods of a customized product must fall within the validity periods of its base product and cannot overlap with the validity periods of another customization of the same base product. Validity periods can fall in the middle of billing cycles and can be backdated as long as the dates fall within the validity of the base product.
Note:
Backdating validity periods is allowed only when you first create a customization. You cannot backdate a customization after it has been created.
See "Validity periods and purchase fees for customized products" and "Validity periods and usage fees for customized products". You can modify the validity periods of a customized product after its creation. For example, you can extend the length of a customization for an additional month.
Note: You cannot modify a customized products validity period in such a way that it no longer falls within the validity of the base product or overlaps the validity of another customized product. Similarly, you cannot modify the validity of a base product in such a way that a customized products validity no longer falls within the validity of the base product.
See the following for information about how validity periods are used to calculate purchase, usage, and cycle fees:
Validity periods and purchase fees for customized products Validity periods and usage fees for customized products Validity periods and cycle fees for customized products
Validity periods and purchase fees for customized products The purchase validity periods of the base and customized products at the time of purchase determine which is used to apply purchase fees. If you customize a product at the time of the initial product purchase and set its purchase validity to begin at the same time as the base product, the purchase fee in the customized product is applied. If the purchase validity of the customized product begins after the initial product purchase, the base products purchase fees are applied. If you customize a product after the initial product purchase, the purchase fee of the customized product is not applied because the base products purchase fee has already been applied. If you want to apply the customized products purchase fee, you must trigger rerating for the purchase event. See "About Rerating" in BRM Setting Up Pricing and Rating. Validity periods and usage fees for customized products The usage validity of the base and customized products at the time of a usage event determine which product is used to rate the event. For example, if a customization has usage validity periods from August 1 to September 1, the usage rates defined in the customized product are used to rate events that occur during that month. Usage rates in the base product are used to rate all other events.
You may need to trigger rerating after customization to ensure that events that fall in the customized products validity periods are rated properly. For example, suppose that the GSM_Basic product rates peak calls at $0.10 per minute. A subscriber makes a 20-minute peak call on January 3, generating a usage event with a $2 balance impact. If a CSR customizes this product on January 5 to reduce the peak usage rate by 25% with validity starting on January 1, you must rerate the January 3 call to ensure that the subscriber is charged correctly. After rerating, the balance impact will be $1.50, so an adjustment event of $0.50 will be applied to the subscribers balance. See "About Rerating" in BRM Setting Up Pricing and Rating for more information about rerating. Validity periods and cycle fees for customized products The cycle validity periods of the customized and base products determine which product is used to apply cycle fees. If a customized product exists at the beginning of the cycle and is valid throughout the cycle, its cycle fees are applied normally. This is also true in cases where a product is customized at purchase time with the customizations validity set to begin at the same time as the base products. The cycle fees of the customized product are used until they are no longer valid. If a customized product is valid for only part of a cycle, it contributes toward the total charge or refund based on the length of its validity. For example, suppose you discount the $10 monthly cycle fee of GSM_Basic by 15% with a validity period of March 1 to April 16. The cycle fee for March will be $8.50, reflecting the 15% discount for the whole month. The cycle fee for April will be $9.25: The cycle fee for the first half of the month is reduced by 15% to $4.25 and the full $5.00 fee is charged for the second half of the month. If you customize a products cycle forward fees in mid cycle, the already charged fees are refunded and new fees are calculated on the validities of the base and customized product. For example, suppose that on April 11 you customize a $10 monthly cycle forward fee by 10%, with validity from April 11 to May 1. BRM refunds the $10 cycle fee that was already paid. It then applies fees separately for the portion of the cycle covered by the base product ($3.33, or 10/30 of $10) and for the portion covered by the customized product ($6.00, or 20/30 of $10 minus 10%). The total cycle fee is therefore $9.33. When the base product and one or more customized products are valid during a cycle, BRM creates separate cycle events to cover the validities of each product. Each event is rated separately based on the rates in the applicable product.
You cannot cancel a customized product after the expiration of its validity.
Cancellation Fees
11-31
When you cancel a base product, BRM applies cancellation fees based on whether a customized product is valid or not:
If a customized product is currently valid, the cancellation fees in the customized product are applied. If no customized product is currently valid, the cancellation fees in the base product are applied.
For example, suppose that the GSM_Basic product has a cancellation fee of $10. You create a customized version of the product with a 50% reduction of the cancellation fee, valid from January 1 to February 1. If the subscriber cancels on January 31, the cancellation results in a $5 balance impact (assuming that cancellation proration is set to Charge for the entire cycle). If the subscriber cancels on February 2, the balance impact is $10. When you cancel a customized product without canceling its base product, no cancellation fees are applied. Cycle fees If you cancel a base product that has cancel proration set to Calculate the charge based on the amount used, the way cycle fees are prorated depends on whether a customized product is valid:
If no customized product is valid, proration is based on the cycle fees in the base product. If a customized product is valid, proration is based on the cycle fees in the customized product. If you cancel a product during a cycle in which both base and customized products are valid, proration is based on the cycle fees and validity of both products. See "Calculating Prorated Cycle Fees and Refunds for Customized Products" in BRM Configuring and Running Billing.
If you cancel a customized product in mid cycle without canceling its base product, the cycle fees for the remainder of the cycle are first refunded based on the fees in the customized product. Cycle fees for the remainder of the cycle are then applied based on the base products fees. For example, suppose that the product GSM_Basic has a cycle forward fee of $10 and cancel proration is set to Calculate the charge based on the amount used. A CSR subsequently customizes this product for a subscriber to reduce the cycle forward fee by 20% with a validity period of January 1 to February 1. If the customized product is canceled on January 16, BRM refunds $4. This amount is the customized products prorated cycle fee for the unused period of January 16 to February 1. Because the base product is now valid, BRM then applies its prorated cycle fee of $5 for the same period. The total cycle fee is $9.
Managing Discounts
In real-time rating, when BRM rates an event, it finds a list of products that apply to the event, filtering by parameters such as service and event time. It sorts the list of qualified products by priority and uses them in that order. BRM checks if any of the qualified products have customizations and, if they do, whether the customizations are still valid. If a customized product is valid, it replaces its base product in the list of qualified products and it is used for rating. Customized products have the same priority as their base products. You can control whether customized products are cached for use by the real-time rating engine. You enable and disable product caching in a /config/business_ params entry. See "Enabling and Disabling the Caching of Customized Products" in BRM System Administrator's Guide.
In pipeline rating, the FCT_Account module populates the CUSTOMER_ DATA.PURCHASED_PRODUCT field of an event data record (EDR) with the accounts purchased products that are valid for the time of the event. This list can include both base products and customized products. FCT_Account also populates the DETAIL.CUST_A.INTERN_RATING_PRODUCTS field with products to be used for rating, along with the priority of each product. The DAT_ AccountBatch module then checks the base products in DETAIL.CUST_ A.INTERN_RATING_PRODUCTS to determine whether customized versions exist. If DAT_AccountBatch finds a customized product for a base product and both products are valid, the base product is removed from DETAIL.CUST_ A.INTERNAL_RATING_PRODUCTS. The customized product is therefore used for rating.
Because advanced customizations modify rates and price models, these changes are applied before charges are reduced by discounting. Charges that you reduce by customization can be further reduced by discounts. For example, suppose the GSM_ Basic product charges $0.10 per minute for peak usage. A 20-minute peak call would result in a $2 balance impact. If you customize the product to reduce the peak usage rate by 25%, that same call results in a balance impact of $1.50. If the subscriber also owns a 10% discount on GSM usage, the balance impact would be further reduced by $0.15, resulting in a final balance impact of $1.35 for the call.
Managing Discounts
Discounts are pricing objects similar to products; customers purchase discounts bundled in a deal.
Purchasing Discounts
When purchasing a discount, you specify the following attributes:
Purchase quantity The discount purchase quantity must be within the minimum and maximum allowed. See "Changing Discount Quantity".
Status The discount status can be active or inactive. See "Setting Discount Status".
Start and end dates The start and end dates specify when the discount begins and ends. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".
For related opcodes, see "Subscription Management FM Standard Opcodes" in BRM Developer's Reference.
Managing Customers Services and Products 11-33
Managing Discounts
Do not call PCM_OP_SUBSCRIPTION_PURCHASE_ DISCOUNT directly. This opcode is always called by the PCM_OP_ SUBSCRIPTION_PURCHASE_DEAL opcode.
Closes the bill. If billing is due, triggers billing. Opens a transaction. Reads the discount object information. Performs the following validations:
Date validation, to make sure that the product is available for purchase. Status validation, to check whether the discount is active or inactive. Ownership quantity validation, to make sure that the discount instance purchase quantity is within minimum and maximum limits for ownership. Purchase quantity validations, to make sure that a partial quantity purchase is not made and to check that the purchased quantity is within the minimum and maximum limits for purchase.
6.
Calculates the start and end dates of the purchase/cycle/usage events based on either CSR customization or pricing object details. If passed relative dates, calculates absolute dates. If Content Manager is configured for time stamp rounding, all start and end dates round to 00:00:00 hours. For more information, see "Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts". If the discount purchase is backdated, validates that:
7.
The date to which the discount purchase is backdated is not prior to the G/L posting date. The date to which the discount purchase is backdated is not prior to the effective date of the account or service. The date to which the discount purchase is backdated is not prior to the date of the last status change of the account or service.
Important:
If you backdate the purchase of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be applied only from the current accounting cycle.
Managing Discounts
If a /config/provisioning_tag object is associated with the discount, this opcode runs the opcodes specified in that object to run at discount purchase time. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating. If applying discount validity rules, sets the cycle and usage start and end dates to one of the following:
9.
The first day of the next accounting cycle (no discount, valid from the middle of the cycle). The discount purchase date (prorated discount, valid from the middle of the cycle). The first day of the current accounting cycle (full discount, valid from the middle of the cycle). The purchase date of the discount (Prorated discount, valid only part of the cycle).
10. Determines whether the discount instance is to be created. If the opcode is not
deferring item discounts or if the opcode has no associated purchase fee, creates a /purchased_discount object with a pointer to the /account object. For some item discounts, an instance is created, but it is removed after the deferred date when the purchase fee is applied.
11. If purchasing discounts in the middle of a cycle and the discount usage map is
configured to support any cycle forward event types, refunds the discounted portion of the cycle forward fee as follows:
a. b.
Checks all discount usage maps to see if the discount supports any cycle forward monthly event types. For each cycle forward event type supported by the discount, checks the charges arrays of all product instances for an array element of the cycle forward event type. Calculates the scale value for the portion of the cycle for which the discount is valid. Sends a request to rate normal prorated events and calculates the resulting prorated balance impact. Sends the event with an inverted flag set for recording.
c. d. e.
12. Generates an audit log for the discount purchase, which sends a request to the
If the discount purchase is successful, PCM_OP_SUBSCRIPTION_PURCHASE_ DISCOUNT returns a message confirming the success.
11-35
Managing Discounts
Validate the purchase time or the billing time if specified by a flag in the input. If the opcode validates the purchase time, any purchase time discounts are selected and validated against the /dependency object. If the opcode validates the billing time, any subscription, system, and shared discounts are selected and validated against the /dependency object. Validate discount-to-discount exclusion rules. Validate discount-to-price-plan exclusion rules, if appropriate.
If one of the operations fails, that operation, and only that operation, cancels. PCM_ OP_SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY returns a validation error and partially creates an account. This opcode validates all the discount rules and returns the resulting discount values in the return flist if PIN_FLD_FLAGS does not get set to PIN_SUBS_FLG_RETURN_ ON_FIRST_ERR in the PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_ DEPENDENCY input flist. This opcode returns an error message when the first error occurs if PIN_FLD_FLAGS is set to PIN_SUBS_FLG_RETURN_ON_FIRST_ERR in the PCM_OP_ SUBSCRIPTION_VALIDATE_DISCOUNT_DEPENDENCY input flist. If the validation fails, this opcode returns a zero result, along with the POIDs of the discounts or plan and discount, whichever operation occurs first.
Canceling Discounts
You typically cancel a discount instance when you cancel the deal in which it is bundled or when you close the account or service that owns the discount instance. You can also cancel a discount instance immediately or backdate the cancellation to a date earlier than the current date. A discount instance gets canceled automatically when the discounts purchase end date has been reached. To cancel a discount instance, you must specify the quantity to cancel:
If the quantity is the same as the quantity purchased by the account or service, the opcode cancels the discount instance. If the quantity is less than the quantity purchased by the account or service, the opcode does not cancel the discount; it subtracts that quantity from the internal count variable within the /purchased_discount object that represents the discount instance.
By default, when you cancel a discount instance, BRM retains the /purchased_ discount object that describes the discount instance with a status of Canceled. You can specify whether to delete /purchased_discount objects or retain them with a status of Canceled. See "Specifying to Delete Canceled Discounts". Changing the status of a discount instance to canceled sets the purchase, usage, and cycle end times to the cancellation time. See "Setting Discount Purchase, Cycle, and Usage Start and End Times". For related opcodes, see "Subscription Management FM Standard Opcodes" in BRM Developer's Reference.
Managing Discounts
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). If necessary, set the value of the keep_cancelled_products_or_discounts entry to 1. Save and close the file. Restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide. Edit the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT policy opcode. By default, this policy opcode keeps /purchased_discount objects when they are canceled. Verify that you set the opcode to cancel, not delete, the discount.
When you change the status of a discount to Canceled, you also set its purchase, usage, and cycle end dates to the cancellation date. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".
Do not delete canceled products if you use delayed billing. See "Rating Delayed Events for Canceled Products". Do not delete canceled products if you rerate events. Events that use deleted products cannot be rerated.
Managing Discounts
2.
0 deletes /purchased_discount objects when you cancel the discount. 1 (default) keeps the canceled discounts in /purchased_discount objects.
3. 4.
Save and close the file. Restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
If you specify a NULL /service object, you cancel discounts associated with the /account object. Otherwise, you cancel discounts associated with the /service object.
You identify discounts to cancel in the PIN_FLD_OFFERING_OBJ (/purchased_ discount POID) field in the input flist. For information about offering objects, see PCM_OP_SUBSCRIPTION_PURCHASE_DEAL. To cancel a discount instance, PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT performs the following tasks:
1.
Validates the discount quantity requested for cancellation. The quantity must be less than or equal to the quantity owned by the account or service. See "Changing Discount Quantity".
Note:
When the quantity to cancel is less than the quantity owned, the discount quantity within the instance is decreased; the discount is not canceled.
2.
The date to which the discount cancellation is backdated is not prior to the G/L posting date. The date to which the discount cancellation is backdated is not prior to the account or services effective date. The date to which the discount cancellation is backdated is not prior to the date of the last status change of the account or service.
Important:
If you backdate the purchase of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be applied only from the current accounting cycle.
Managing Discounts
3.
If a /config/provisioning_tag object is associated with the discount, this opcode runs the opcodes specified in that object to run at discount cancellation time. See "Using the Provisioning Tag Framework" in BRM Setting Up Pricing and Rating. Sets the purchase, cycle, and usage end dates for the /purchased_discount object to the cancellation date. See "Setting Discount Purchase, Cycle, and Usage Start and End Times". If you set a discount validity rule, it sets the PIN_FLD_USAGE_END_T and PIN_ FLD_CYCLE_END_T fields to one of the following:
4.
5.
The first day of the next accounting cycle. The discount cancellation date.
For more information on discount validity rules, see "About Applying Discounts Activated or Canceled in Mid-Cycle" in BRM Configuring Pipeline Rating and Discounting.
6.
Calls the PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT policy opcode and does one of the following:
Deletes the /purchased_discount object associated with the service or account. Sets the status of the /purchased_discount instance to Canceled without deleting it.
If the account is the parent of a discount sharing group, it also deletes, or cancels without deleting, the /purchased_discount object from the list of discounts shared by the account.
7.
Applies cycle fees or refunds discounted cycle fee amounts. See "Prorating Cycle Fees After a Discount Purchase or Cancellation" in BRM Configuring and Running Billing.
Note:
If the discounts validity period is configured to start on first usage and has not yet been set, the discount has not been activated. In this case, cycle fees and refunds on discounted cycle fees are not applied.
8.
You can also keep or delete canceled discounts by setting a configuration parameter. See "Specifying to Delete Canceled Discounts".
11-39
Managing Discounts
By default, when you cancel a /purchased_discount object, you set its status to Canceled. In addition, you set the end date to the discount cancellation date. The PCM_OP_SUBSCRIPTION_POL_SPEC_CANCEL_DISCOUNT policy opcode allows you to specify whether to delete the /purchased_discount object or retain it with a status of Canceled.
Note:
When delayed usage events are expected to be loaded into BRM, BRM requires information stored in the /purchased_discount object to rate the delayed events. In this case, the /purchased_discount object should always be retained with a status of Canceled and should not be deleted.
You can customize the behavior of this policy opcode by setting the PIN_FLD_ ACTION field to one of these values:
PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_ONLY, which sets the status of the /purchased_discount object to Canceled and does not delete it. PIN_BILL_CANCEL_PRODUCT_ACTION_CANCEL_DELETE, which deletes the /purchased_discount object. PIN_BILL_CANCEL_PRODUCT_ACTION_DONOT_CANCEL, which stops the cancellation of the discount.
Note:
Discount quantity. See "Changing Discount Quantity". Discount status. See "Setting Discount Status". Discount purchase, usage, and cycle start and end times. See "Setting Discount Purchase, Cycle, and Usage Start and End Times".
You use Customer Center to modify these discount attributes. See "Managing Discounts". For related opcodes, see "Subscription Management FM Standard Opcodes" in BRM Developer's Reference.
Managing Discounts
When you purchase a discount: you can set the status to Active or Inactive in the case of deferred purchase. When you purchase an inactive discount: you can later reactivate it by setting its status to Active. When you cancel a discount: you set the discount status to Canceled. See "Canceling Discounts". When you change the status of an account or service that owns a discount: you change the status of the discount to the same status; when you close an account, you cancel any discounts it owns.
Setting Discount Purchase, Cycle, and Usage Start and End Times
You specify a discounts validity period for the account that purchases the discount by setting the purchase start and end times. The cycle and usage start and end times specify when to start and stop charging cycle forward fees and rating usage events by using the discount rate. For more information, see "About Product and Discount Validity Periods" in BRM Setting Up Pricing and Rating. You can modify a discounts purchase, usage, and cycle start and end times at the following times:
When purchasing a discount. When canceling a discount. By default, the discounts purchase, cycle, and usage end times are set to the cancellation time. You can change the date the discount expires by modifying the discounts end time. When changing the status of a discount.
Important:
Do not change a discounts purchase, cycle, or usage start time after the discount has been applied to the account; otherwise, the discount will be applied incorrectly.
BRM does not allow you to backdate the discounts purchase, usage, or cycle end date prior to the discounts purchase start date or prior to the G/L posting date. See "About backdated purchase, usage, or cycle end dates". The cycle and usage periods must start after the purchase period start time and end before the purchase period end time. If you configure BRM for time stamp rounding, BRM rounds all start and end times to 00:00:00 hours. When setting the validity period during discount purchase, Customer Center calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL. See "Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts".
11-41
Managing Discounts
When changing the validity periods of a purchased discount, Customer Center calls the PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO opcode. See "How Purchase, Cycle, and Usage Validity is Modified".
Do not change a discounts purchase, cycle, or usage start time after the discount has been applied to the account; otherwise, the discount will be applied incorrectly.
If you change the purchase, cycle, or usage start time from first usage to an absolute date, the opcode generates an event that causes Pipeline Manager to update the validity period in the pipeline database. The start and end times are stored in the accounts /purchased_discount object. PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO performs the following tasks:
1.
Resets the /purchased_discount objects purchase, cycle, and usage start and end times to the times specified in the input flist. If discount validity rules are set, PCM_OP_SUBSCRIPTION_SET_ DISCOUNTINFO sets the start and end times accordingly. See "Implementing Discount Validity Rules" in BRM Configuring Pipeline Rating and Discounting.
2.
For backdating operations, validates and sets the discounts purchase, cycle, and usage end dates to a backdated date. See "Setting Discount Purchase, Cycle, and Usage Start and End Times". Applies cycle fees or refunds discounted cycle fee amounts. See "Prorating Cycle Fees When a Discounts Cycle Start or End Date is Changed" in BRM Configuring Pipeline Rating and Discounting. When only the purchase period is changed and the cycle period starts on first usage, if the validity of the cycle period has not been initialized by a first-usage event, this opcode does not apply cycle fees or refund discounted cycle fee amounts.
Note:
3.
4.
Managing Deals
For general information about modifying a discount in a deal, see "Modifying Discount Attributes".
Managing Deals
A deal consists of one or more products and discount objects. By bundling products into a deal, you can provide discounts for those products. For example, you can create a deal that waives the sign-up fee if the customer registers before a certain date. You can add or upgrade a customers products by purchasing deals after you create the account. Customers can purchase a deal only if they have already purchased a plan that includes the service that the deal offers. For example, if a customer has already purchased a product that uses the email service, the customer can purchase another email deal. To purchase a deal that has a different service, you add the deal to another plan and then add the plan with the new service. See "Purchasing Deals". You can associate a deal with a particular service or with any service owned by an account. You can set up deal transitions that determine which deals can be purchased subsequently to another deal. See "Transitioning Deals". You can set up deal dependencies that determine which deals you allow a customer to own. See "Defining Deal Dependencies". You can customize account-level deals during plan transitions. See "Customizing Account-Level Deals During Plan Transitions" for more information.
Purchasing Deals
You can add or upgrade products for customers by purchasing deals after you create the account. Customers can purchase a deal only if they have already purchased a plan that includes the service that the deal offers. For example, if a customer has already purchased a product that uses the email service, the customer can purchase another email deal. You can also backdate deal purchases. You purchase deals for customers from the Plans tab of Customer Center. For information on how deals are purchased, see "How Deals are Purchased".
11-43
Managing Deals
Note:
If the customer upgrades to a deal that includes more free hours, cancel the old deal before purchasing the new deal. See "Canceling Products". When you purchase a deal, you can customize it by modifying one or more products in the deal. See "Modifying Products" and "Customizing Product Pricing". When you purchase a deal, you can backdate the purchase date for all of the products it contains by using the purchase wizard. You need the proper permissions to purchase or modify a deal. To modify a deal, the deal must be defined as customizable. You define this property in your price list.
Deals that must be owned before another can be purchased. Deals that are required in a plan. Deals that cannot be owned at the same time. Deals that you can upgrade or downgrade to.
If you specify a /service object, you purchase the deal for that service as a service-level deal. The /service object must belong to the account. If you specify a NULL /service object, you purchase the deal for the /account object as an account-level deal. If multiple deals are purchased for the same service type, the value of the /service objects PIN_FLD_SERVICE_ID field identifies the service instance for the deal.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL creates an identifier for each deal purchase. This identifier is stored in the PIN_FLD_PACKAGE_ID field in the /purchased_product and /purchased_discount objects. The identifier distinguishes products and discounts bundled as part of a deal or a plan purchase.
Managing Deals
Note:
PIN_FLD_PACKAGE_ID is unique for every deal, except when deals are purchased in the same plan. In this case, all the offerings in the deals within the plan will have the same PACKAGE_ ID. If you need to uniquely identify such a deal: to cancel it, for example, you need to provide the /service object along with the PACKAGE_ID. If the deals share the same service, you must also provide the /deal object.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL sets the purchase, cycle, and usage validity periods of the products and discounts in a deal. For more information, see "Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts". If the deals products or discounts grant resources that start on first usage (when the subscriber impacts the resource balance for the first time), you can specify that the validity period of all resources in the deal that start on first usage are set when one of those resources is impacted for the first time. To do this, set the PIN_FLD_GRANT_ RESOURCES_AS_GROUP flag value in the PIN_FLD_FLAGS field. If you set the deal for on-demand billing, PCM_OP_SUBSCRIPTION_PURCHASE_ DEAL helps to create the on-demand bill for purchase fees for products associated with the deal. You set up on-demand billing for deals and plans by using Pricing Center. Before you purchase a deal, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls the PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY opcode to validate deal dependencies. If dependencies exist, the deal purchase cancels. In addition, if you set a validate_discount_dependency entry in the /config/business_ params object, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL checks for a mutually exclusive relationship between any discounts packaged in the deal and any plan the account already owns. The opcode retrieves the list of subscribed discounts and price plans and it calls the PCM_OP_SUBSCRIPTION_VALIDATE_DISCOUNT_ DEPENDENCY opcode to validate any mutual dependencies. If the opcode detects such a relationship, the deal purchase cancels. If no mutually exclusive relationship exists, the deal purchase continues. For more information, see "About Discount Exclusion Rules" in BRM Configuring Pipeline Rating and Discounting.
Note:
Dependencies are not checked if the deal originated in an external customer relationship management (CRM) application. In that case, the input flist contains a type-only deal POID because no actual BRM deal exists. The opcode requires no validation if the PCM_OP_ SUBSCRIPTION_CANCEL_DEAL opcode was called from the PCM_OP_CUST_COMMIT_CUSTOMER opcode or the PCM_ OP_CUST_MODIFY_CUSTOMER opcode.
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls the PCM_OP_SUBSCRIPTION_ PURCHASE_PRODUCT opcode to create /purchased_product objects for each product in the deal. If a product is customized at the same time as it is created, PCM_ OP_SUBSCRIPTION_PURCHASE_PRODUCT is called multiple times to create the base product and its customized products.
11-45
Managing Deals
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL uses the PIN_FLD_FEE_FLAG field to control whether PCM_OP_SUBSCRIPTION_PURCHASE_PRODUCT applies fees. See "Applying Purchase and Cycle Fees to the Balance". When the deal and all products and discounts for the deal have been purchased, the opcode records an /event/billing/deal/purchase event in the database for auditing purposes. If you successfully purchase the deal, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL returns the /account POID and the POID of the /event/billing/deal/purchase event. You do not purchase the deal in the following cases:
If the /service object does not belong to the /account object. If the /account object or /service object is not valid. If status flags are not set for provisioning.
A closed account may purchase a deal if the CM configuration file has this entry set to 1:
- cm deal_purchase_for_closed_account 1
Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts
Purchase, cycle, and usage validity periods define when products and discounts are valid and when product fees are charged and discounted. For more information, see "About Product and Discount Validity Periods" in BRM Setting Up Pricing and Rating. PCM_OP_SUBSCRIPTION_PURCHASE_DEAL calls PCM_OP_SUBSCRIPTION_ PURCHASE_PRODUCT and the PCM_OP_SUBSCRIPTION_PURCHASE_ DISCOUNT opcode, which set the purchase, cycle, and usage validity periods of the deals products and discounts, respectively. If the system is configured for time stamp rounding, PCM_OP_SUBSCRIPTION_ PURCHASE_PRODUCT and PCM_OP_SUBSCRIPTION_PURCHASE_DISCOUNT round the start and end times to 00:00:00 hours. When called by Customer Center, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL uses the purchase, cycle, and usage validity dates that are specified in the /deal object by default. If you specify alternative validity periods for products and discounts, those validity dates permanently override the dates specified in the /deal object.
Note:
Dates for advanced customizations do not permanently override the dates of the base product. When advanced customizations are not valid, the base product is selected for rating the customers usage. For more information, see "Customizing Product Pricing".
To set the purchase, cycle, and usage start and end times, pass the following values in opcode input flists in the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays. In the following fields, the asterisk (*) indicates either PURCHASE, CYCLE, or USAGE.
Note:
The cycle and usage validity periods must fall entirely within the purchase validity period.
Managing Deals
Specify the start time as follows: To start immediately (when the product or discount is purchased), set the value of PIN_FLD_*_START_T and PIN_FLD_*_START_UNIT to 0. The opcode sets the start time to the purchase time. To start on first usage (when the subscriber uses the product or discount for the first time) set the PIN_FLD_*_START_UNIT field to -1 and the PIN_FLD_ *_START_OFFSET field to 0. To start relative to the purchase time, set the relative unit (for example, days or cycles) in PIN_FLD_*_START_UNIT and set the number of relative units in PIN_FLD_*_START_OFFSET. The relative start time is calculated by adding the relative offset period to the purchase time.
Specify the end time as follows: To never end, set the value of PIN_FLD_*_END_T and PIN_FLD_*_END_ UNIT to 0. To end relative to the start time, set the relative unit (for example, days or cycles) in PIN_FLD_*_END_UNIT and set the number of relative units in PIN_FLD_*_END_OFFSET. The relative end time is calculated by adding the relative offset period to the start time.
For more information about the unit and offset values, see "Specifying purchase, cycle, and usage start and end times". When the product or discount is purchased, the start and end times are calculated based on the purchase time. The validity period is set in the PIN_FLD_*_START_T and PIN_FLD_*_END_T fields of the accounts /purchased_product and /purchased_ discount objects. If the validity period has a relative start or end time, the details about the relative offset are stored in the PIN_FLD_*_START_DETAILS and PIN_FLD_*_END_DETAILS fields of the purchased product or purchased discount. The details fields store three values: the mode of the validity period, the relative offset unit, and the number of offset units in the relative period. For more information, see "Storing relative start and end times for accounts products and discounts". Specifying purchase, cycle, and usage start and end times When the purchase, cycle, or usage period has an absolute start time (starts and ends on a specific date and time), the start and end times are passed in opcode flists in time stamp fields:
When the purchase, cycle, or usage period has a relative start or end time, the details about the relative period are passed in opcode flists in unit and offset fields:
11-47
Managing Deals
These offset fields specify the number of units in the relative period: PIN_FLD_PURCHASE_START_OFFSET PIN_FLD_PURCHASE_END_OFFSET PIN_FLD_CYCLE_START_OFFSET PIN_FLD_CYCLE_END_OFFSET PIN_FLD_USAGE_START_OFFSET PIN_FLD_USAGE_END_OFFSET
The unit and offset fields are used in combination to determine the relative offset of the purchase, cycle, and usage periods. For example:
If a products PIN_FLD_CYCLE_START_UNIT has a value of 8 (accounting cycles) and PIN_FLD_CYCLE_START_OFFSET has a value of 3, the cycle fee starts three accounting cycles after the product is purchased. If a discounts PIN_FLD_PURCHASE_END_UNIT has a value of 8 (accounting cycles) and PIN_FLD_PURCHASE_END_OFFSET has a value of 3, the discount expires three accounting cycles after it is activated.
You can specify any number of units in the offset fields, up to 1048576. This is equivalent to approximately 12 days in seconds, 728 days in minutes, and 119 years in hours. The relative offset information in the unit and offset fields is stored in the BRM database in details fields. For more information, see "Storing relative start and end times for accounts products and discounts". About backdated purchase, usage, or cycle end dates Setting a product purchase, usage, or cycle start dates to a backdated date is different from backdating a purchase itself. When the product purchase, usage, or cycle start dates are set to a backdated date, though the cycle charges are applied from the backdated date, the change is effective only from the current time. For example, you purchase a product on February 1, and set the PURCHASE_ START_ T, USAGE_START_T, and CYCLE_START_T fields of the product to a backdated date of January 15. In this case, the charges are applied from January 15, but the creation time of the product remains February 1 (current time). Thus, if usage events during the period of January 15 to February 1 are rerated, they are not rated with this product.
Managing Deals
Here, if you enter January 15 as PIN_FLD _END_T in the opcode, the product becomes effective from January 15 (the creation time of the product is set to January 15), and the charges are also applied from the backdated date of January 15. Oracle recommends that you use the latter procedure for backdating a purchase.
Note:
You cannot set the discount PURCHASE_ START_T, USAGE_ START_T, and CYCLE_START_T to a backdated date.
Similarly, backdating a product or discount's purchase, usage, or cycle end dates is different from backdating the cancellation. When the product or discount's purchase, usage, or cycle end dates are set to backdated date, though the cycle charges are refunded from the backdated date, the change is effective only from the current time. For example, on February 1, you set the PURCHASE_ END_T, USAGE_END_T, or CYCLE_END_T fields of a product to the backdated date of January 15. In this case, the charges are refunded from January 15, but the change in the END_T to January 15 is effective only from the current time (February 1). Thus, if usage events during the period of January 15 to February 1 are rerated, they are rated with this product. Here, if you enter January 15 as PIN_FLD _END_T in the opcode, the product is available for rating from January 15, and the charges are also refunded from the backdated date of January 15. BRM does not allow you to backdate the following:
The product purchase start date if the purchase start date has elapsed. For example, on January 1, a product is purchased with the purchase start date set to January 15. On January 10, you can backdate the purchase start date to January 5. But, you cannot backdate the purchase start date on January 16; that is, you cannot backdate the purchase date when the January 15 date has passed.
The product cycle start date if the cycle start date has elapsed. The usage and cycle end date of a product prior to its purchase start date. The purchase, usage, and cycle end date of a discount prior to its purchase start date. The purchase, usage, or cycle start and end dates of a product prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date". The purchase, usage, and cycle end dates of a discount prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date".
Example of backdated purchase, usage, cycle start and end dates On April 1, consider that you create an account that owns a product with $9.95 as a cycle forward fee, 3600 as Anytime Minutes, and the start date set to June 20. On May 2, you change the start date to April 16. The charges will be as follows:
$4.98 monthly charges and 1800 Anytime Minutes for the period from April 16 to May 1. $9.95 monthly charges and 3600 Anytime Minutes for the period from May 1 to June 1.
11-49
Managing Deals
To backdate the purchase, usage, or cycle start or end dates of a product or purchase, usage, or cycle end date of a discount during purchase, enter the backdated date in the respective date fields. After a product is purchased, use the PCM_OP_SUBSCRIPTION_SET_PRODINFO opcode to backdate the purchase, usage, or cycle start and end dates. Similarly, use the PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO opcode to backdate the purchase, usage, or cycle end dates of the discount.
Important:
If you set the end date of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be refunded only for the current accounting cycle.
Storing relative start and end times for accounts products and discounts Relative validity information in the PIN_FLD_*_UNIT and PIN_FLD_*_OFFSET fields that are passed in opcode flists are stored in the database in details fields:
When products and discounts are purchased, the details fields are stored in /purchased_product and /purchased_discount objects. The start-details and end-details fields are 32-bit integer fields that store the mode of the validity period, the relative offset unit, and the number of offset units in the relative period:
Mode: The mode specifies generally when the validity period starts or ends. The mode is stored in the lower 8th bit. When a product or discount is purchased, its start and end dates are set and the mode value in the start-details field is set to PIN_VALIDITY_ABSOLUTE (a value of 0). The end-details field can have a value of PIN_VALIDITY_ABSOLUTE if the end date is specified or a value of PIN_VALIDITY_NEVER (a value of 2) if the validity period never ends. Before the product or discount is purchased, the mode in the details field of the product or discount in the /deal object can also specify other values such as immediate and relative. The mode helps to determine how the start and end times are set when the product or discount is purchased. For more information, see "Storing Start and End Times for Products and Discounts in a Deal" in BRM Setting Up Pricing and Rating.
Note:
Relative offset unit: This value specifies the type of offset unit and corresponds to the value of PIN_FLD_*_START_UNIT or PIN_FLD_*_END_UNIT that is passed in opcode flists. The relative offset unit is stored in the next four bits of the details field and can have one of these values:
Managing Deals
Number of offset units: This value specifies how many offset units are in the relative period and corresponds to the value of PIN_FLD_*_START_OFFSET or PIN_FLD_*_END_OFFSET that is passed in opcode flists. The number of offset units is stored in the remaining 20 bits of the details field.
Modifying Deals
You use Pricing Center to modify deals in the BRM database. Changes you make to deals in the database do not affect the deals already owned by customer accounts. You can change the valid deal period or the products associated with the deal, and you can define prerequisites, mutually exclusive relationships, or transitions for deals. See Pricing Center Help for more information. You use Customer Center to modify deals owned by customer accounts; for example, to transition to a new deal.
To validate deal-to-deal transitions, use the PCM_OP_ SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY opcode. See "Validating Deal Transitions".
Performs validation checks on all of the deals. Calls the PCM_OP_SUBSCRIPTION_CANCEL_DEAL opcode to remove any canceled deals. Removes the deals to be canceled from an accounts list of deals. Calls the PCM_OP_SUBSCRIPTION_PURCHASE_DEAL opcode to add the new deals to the accounts list of deals. Applies proration rules to the products. If any cancellation or purchasing fees are defined, they are charged. If a deal created by PCM_OP_SUBSCRIPTION_CHANGE_OPTIONS requires a new service, calls the PCM_OP_CUST_MODIFY_CUSTOMER opcode to create that service. Creates an /event/billing/product/action/cancel object for the canceled deals.
7.
Managing Deals
PCM_OP_SUBSCRIPTION_CHANGE_DEAL calls PCM_OP_SUBSCRIPTION_ CANCEL_DEAL to cancel the subscription products associated with a deal and then calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to purchase new subscription products and associates them with the deal. PCM_OP_SUBSCRIPTION_CHANGE_DEAL generates two notification event objects:
The /event/notification/deal/change object signifies change progress. The information in the object indicates the canceled deal. The /event/notification/deal/change_complete object signifies change completion. The information in the object indicates the new purchased deal.
PCM_OP_SUBSCRIPTION_CHANGE_DEAL returns the POIDs of the event objects created by PCM_OP_SUBSCRIPTION_DEAL and PCM_OP_SUBSCRIPTION_ PURCHASE_DEAL. If cancellation or purchase transactions fail, PCM_OP_SUBSCRIPTION_CHANGE_ DEAL rolls back any changes made. If any part of the transaction fails, the products associated with the account are not changed.
Transitioning Deals
To transition deals, you use Pricing Center to set up transition rules, which are applied when you upgrade or downgrade a deal for a customer. This enables you to limit the deals that customers can switch to and still remain fully provisioned. A deal cannot be transitioned under the following circumstances:
The new deal is mutually exclusive to a deal currently in the account. The account is missing a necessary prerequisite deal. The deal is associated with an inactive service. The service being transitioned from and the service being transitioned to are not the same service. The deal is required in the associated plan.
Confirms that the validate_deal_dependencies entry in the CM pin.conf file exists and, if so, performs validations; if not, it does nothing. See "Enabling Deal Dependencies Validation". Checks for a PIN_TRANS_NAME_DEAL_VALIDATION entry in the input flist. If this entry exists, the validation checks have already been performed within the current transaction. Verifies that the input is a list of deals. If PIN_FLD_DELETED_FLAG is set to 1, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY performs the validations required if those deals were already deleted.
2.
3.
Managing Deals
If the deals pass all validation checks, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_ DEPENDENCY returns a PIN_FLD_RESULT value of True. If any deal violates any of the validation checks, this opcode fails and returns a PIN_FLD_RESULT value of False. If the validation fails because the two deals are mutually exclusive, PCM_OP_ SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns the POIDs of the two deals and a message indicating that the two deals are mutually exclusive. If the validation fails because a prerequisite deal is missing, PCM_OP_ SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY returns the POID of the deal missing a prerequisite.
Calls the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL policy opcode to perform any custom validation that you may have added. See "Customizing Deal Transitions". Checks the /dependency and /transition objects to make sure that the deal transition does not violate any transition rules. Checks the /deal object to make sure that the deal being transitioned is not a required deal in the associated plan. If it is required, the transition is not performed. Performs the transition. Charges cancellation fees for the old deal and purchase fees for the new deal based on these flags in the /transition object:
2. 3.
4. 5.
0 charges fees. 1 waives purchase fees. 2 waives cancellation fees. 3 waives purchase and cancellation fees.
Note:
These fees are always prorated regardless of the products cancellation proration setting.
Important:
The PCM_OP_SUBSCRIPTION_TRANSFER_ SUBSCRIPTION opcode transitions valid services with a status of Inactive, but those services remain permanently inactive after the transition.
6.
During the transition, calls the PCM_OP_BILL_CYCLE_FORWARD opcode and the PCM_OP_BILL_CYCLE_ARREARS opcode to prorate the cycle fees, if necessary. If the PIN_TRANS_PRO_NORMAL_ON_TRANSITION flag is set, any new products prorate the last cycle fee and the first cycle fee. This flag overrides the user proration settings for product purchases and cancellations.
11-53
Managing Deals
To get a list of deals and products available for transition, use the PCM_OP_ CUST_POL_TRANSITION_DEALS policy opcode. Customer Center calls this policy opcode to return the list of deals available for an account to transition to and the products the deals contain. This policy opcode takes a deal POID and transition type (usually upgrade or downgrade) as input, reads the /transition object, and returns the list of deals available for transition, including their product names and descriptions. Use the PCM_OP_CUST_POL_TRANSITION_DEALS policy opcode to perform any additional filtering of deals before they are returned as available for transition. For example, use this policy opcode to limit certain deals to customers in a specific city.
To validate how deals are transitioned, use the PCM_OP_SUBSCRIPTION_POL_ PRE_TRANSITION_PLAN policy opcode. This policy opcode allows customized validation based on account data during deal-to-deal transitions. For example, you may restrict a deal transition to customers from a particular location or require that customers own the first deal for a specific period of time before allowing the transition to a different deal. The PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_DEAL policy opcode is called by PCM_OP_SUBSCRIPTION_TRANSITION_DEAL before it performs any validation checks. By default, the PCM_OP_SUBSCRIPTION_POL_PRE_ TRANSITION_DEAL policy opcode is an empty hook provided to facilitate customization. Usually, customization consists of transition rules based on account data.
Note:
To customize how to transition a plan from one account to another, use the PCM_OP_SUBSCRIPTION_POL_PRE_ TRANSITION_PLAN policy opcode. See "Customizing Plan Transitions Without Configuring /transition Objects".
Prerequisites. Specifies that an account must own a particular deal to be able to purchase an additional deal.
Managing Deals
Note:
A prerequisite can contain deals of different services. For example, to own a GPRS deal, an account must own a GSM deal.
Required deal. Specifies whether deals are optional or required for plans. Required deals must be purchased when a plan is purchased, whereas optional deals can be added to an account at any time. Mutual exclusivity. Sets up a mutually exclusive relationship between two deals, so if an account owns one deal, it cannot own the other. Allowed transitions. Specifies which deals or plans can serve as replacements for others. Transitions specify the deals that customers can switch to and remain fully provisioned. While transitioning from one deal to another, your customers retain their devices, such as phone numbers and services. Customers owning deals associated with a primary service may transition to other deals associated with that primary service. The list of deals displayed as available for transition are all associated with a specific primary service.
Open the CM configuration file BRM_Home/sys/cm/pin.conf. Uncomment the validate_deal_dependencies entry to enable the deal dependencies validation:
- fm_utils validate_deal_dependencies 1
3. 4.
Save and close the file. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Pass in an account and a list of deals. PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY checks whether owning the deals in the account and the deals you send would violate any dependency rules. You can also send in an account and a plan, and this opcode performs the validation checks for the deals in the account and the deals in the plan.
Pass in a list of deals to validate against another list of deals. PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY validates that owning both sets of deals would not violate any dependency rules.
In the first case, PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY accepts the POID for an account and validates that the deals in that account do not violate any deal dependency rules set in the /dependency object. You can also send in
11-55
Managing Deals
a /plan object, and PCM_OP_SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY runs the validation checks between the deals in the /account and the deals in the plan. If any deal violates a dependency relationship, the operation fails. To validate two sets of deals, send in /account -1 (without a POID); PCM_OP_ SUBSCRIPTION_VALIDATE_DEAL_DEPENDENCY validates the deals. If any of the deals violates a dependency relationship, the operation fails.
Maintain any deleted products in the /purchased_product objects to allow product-level and discount-level validations. To do so, set the value of the keep_cancelled_products_or_discounts entry to 1 in the pin.conf configuration file for Connection Manager. See "Specifying to Delete Canceled Products" for more information.
Perform prerequisite and mutual exclusivity rule dependency validation. To do so, verify that the validate_deal_dependencies entry is uncommented in the pin.conf configuration file for Connection Manager. See "Enabling Deal Dependencies Validation" for more information.
Perform deal dependency validations on inactive or canceled products and discounts. To do so, enable the ProductLevelValidation business parameter in the /config/business_params object in the BRM_Home/sys/data/config/bus_params_ subscription.xml file. By default, ProductLevelValidation is set to disabled. See "Enabling Deal Dependency Validations for Inactive or Canceled Products and Discounts" for more information.
Note:
BRM performs the purchase time dependency validations between deals irrespective of the value of the ProductLevelValidation parameter.
How BRM Acts on Deal Dependencies for Inactive or Canceled Products and Discounts
When BRM is appropriately configured to enforce deal dependency validations for inactive or canceled products or discounts and a deal A is the prerequisite of deal B:
If deal B is owned by the account, BRM will not allow cancellation or inactivation of any products or discounts of deal A unless all the products or discounts of deal B are in canceled or inactive state. If any product or discount of deal A is in the canceled state, deal B cannot be purchased. If any product or discount of deal A is in the inactive state, deal B can be purchased only in an inactive state; that is, all products and discounts of deal B
Managing Deals
have to be purchased as inactive. All the products or discounts in prerequisite deal A should be first activated before activating the products or discounts in deal B.
Note: BRM does not perform validations between the validity dates of the prerequisite and dependent deals.
Enabling Deal Dependency Validations for Inactive or Canceled Products and Discounts
Use the pin_bus_params utility to configure the ProductLevelValidation business parameter to enable deal dependency validations for inactive or canceled products and discounts. To do so:
1.
Create an editable XML file from the subscription instance of the /config/business_params object by using the following command: pin_bus_params -r BusParamsSubscription bus_params_ subscription.xml BRM places the XML file named bus_params_subscription.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.
2. 3.
Locate the ProductLevelValidation entry in bus_params_subscription.xml.out. Set the value of ProductLevelValidation as required. Your entry should be one of the following:
<ProductLevelValidation>enabled</ProductLevelValidation> <ProductLevelValidation>disabled</ProductLevelValidation>
4. 5.
Save this updated file as bus_params_subscription.xml. Load the modified XML file containing the business parameters for subscription into the appropriate /config/business_params object in the BRM database. pin_bus_params bus_params_subscription.xml You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see the description for pin_bus_params in BRM Developer's Guide.
6.
Read the object with the testnap utility or Object Browser to verify that all fields are correct. For more information on reading objects by using the Object Browser, see BRM Managing Customers. For instructions on using the testnap utility, see BRM Developer's Guide.
7. 8.
Stop and restart Connection Manager. See the description for starting and stopping the BRM system in BRM System Administrator's Guide. For multiple databases, run the pin_multidb script with the -R CONFIG parameter. For more information on this script, see pin_multidb in BRM System Administrator's Guide.
Canceling Deals
You can cancel all the products in a deal in one operation, or you can cancel individual products. Canceling a deal is particularly useful when a customer wants to upgrade. You can cancel all of the products in the old deal as a group before purchasing the new
11-57
Managing Plans
deal for the customers account. You can cancel a deal immediately or backdate the cancellation of a deal to a date earlier than the current date. You use Customer Center to cancel deals.
Note:
After you cancel a deal, you cannot reactivate the deal or the products it contains. You cannot cancel a required deal. Instead, either transition to a new plan or close the service associated with the deal. See "About Plan Transitions in BRM".
Opens a transaction. Checks if the deal is required within the corresponding plan. If so, the cancellation is not permitted. From the input flist, retrieves the PIN_FLD_PACKAGE_ID, PIN_FLD_SERVICE_ OBJ, name, and type of the products and discounts associated with the deal. If the deal being canceled has the same PIN_FLD_PACKAGE_ID and PIN_FLD_ SERVICE_OBJ as another deal, then PIN_FLD_DEAL_OBJ is also required to uniquely identify the deal.
4. 5.
Validates that the deal is available for cancellation. For each product, PCM_OP_SUBSCRIPTION_CANCEL_DEAL calls the PCM_ OP_SUBSCRIPTION_CANCEL_PRODUCT opcode to cancel the product. The opcode does not directly delete customized products in the deal whose base products are also included in the deal. Customized products are automatically deleted when their base products are deleted by PCM_OP_SUBSCRIPTION_ CANCEL_PRODUCT. The opcode does delete customized products whose base products are not included in the deal.
6. 7. 8.
For each discount, PCM_OP_SUBSCRIPTION_CANCEL_DEAL calls the PCM_ OP_SUBSCRIPTION_CANCEL_DISCOUNT opcode to cancel the discount. Creates an /event/billing/deal/cancel object for auditing purposes. If the deal cancel is successful, returns the /account POID and the POID of the /event/billing/deal/cancel event.
Managing Plans
You add new services to an account by purchasing a plan. Plans provide the deals, products, and discounts needed for configuring the new services. You can also backdate plan purchases. You also use plans to set and change credit limits in an account. For more information, see "Changing a Customers Credit Limit".
11-58 BRM Managing Customers
Managing Plans
Not defined, set as (0). Upgrade, set as (1). Downgrade, set as (2). Generation change, set as (3). See "Defining a Generation Change for Plans". Custom transition type. See "Creating Custom Transition Types for Deals and Plans".
If the transition type is a generation change, the two plans do not have to share the same primary service. If the transition type is an upgrade or a downgrade, the two plans must share the same primary service. If the source and target plans are a valid combination, you can configure the transition rule such that the source plan retains the non-currency grants as valid to the end of the cycle. To do so, set the value of PIN_FLD_FLAGS input to the PCM_ OP_SUBSCRIPTION_TRANSITION_PLAN opcode to be PIN_SUBS_ TRANSITION_CONTROL_ROLLOVER. (See pin_subscription.h.) BRM checks the status of any add-on deals (deals that are not part of the source plan) owned by the account. If all add-on deals are canceled, BRM closes the associated services and transitions the account to the target plan. If the add-on deals are not canceled, BRM returns an error and retains the source plan for the account. Therefore, you must first cancel all add-on deals owned by the account before you transition the account to the target plan.
You cannot backdate a plan-transition or generation change to a prior period. If you delete a service from a plan, BRM closes that service and sets its status to PIN_STATUS_FLAG_DUE_TO_TRANSITION. You cannot change the status of a closed service.
11-59
Managing Plans
BRM does not transfer extended rating attributes (ERAs) data during a plan transition or a generation change. For example, if you have an account with ERA on friends and family and perform a plan transition or generation change, the ERA data is not transferred to the new plan. BRM, by default, retains the credit limits associated with the source plan for an account when the source and target plans for that account are associated with the same balance group but each plan has different credit limits. To set new credit limits for the account, you can customize PCM_OP_CUST_POL_TRANSITION_ PLAN opcode by doing the following:
1. 2.
Set the credit limit in the PIN_FLD_LIMITS array. Pass this array in the input flist to the PCM_OP_SUBSCRIPTION_ TRANSITION_PLAN opcode,
Customize the PCM_OP_SUBSCRIPTION_POL_PRE_ TRANSITION_PLAN policy opcode for only the plan transitions for which a /transition object is not defined in Pricing Center.
When BRM attempts to transition an account and the plan transition rule does not have a /transition object, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN uses the following information you provide in the output flist of the PCM_OP_ SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode:
Your specification on whether to charge any cancellation fees associated with the source plan for the account and purchase fees for the new product for this transition. The Primary Basic Service (PBS) that must apply to the plan transition.
Managing Plans
Note:
If you do not provide these values, the opcode searches for a /transition object and if no /transition object exists for the transition rule, the transition will fail.
You can provide these values to handle some plan transitions and configure plan transition rules in Pricing Center for others. For information on the PCM_OP_ SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode, see BRM Developer's Reference. Note that:
You can customize plan transitions in this way if the transition does not involve a generation change. You cannot customize deal transitions in this manner. Pricing Center must be used to set up transition rules to transition deals. You cannot transition plans under certain conditions. For example, you cannot transition a plan when add-on deals that are not part of the original plan are active and owned by the account.
Calls the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode to perform any custom validations. When the PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode completes its actions, it passes the values provided by you to PCM_OP_ SUBSCRIPTION_TRANSITION_PLAN opcode.
2.
For plan transitions where there is a /transition object for the transition rule, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN checks the /dependency and /transition objects to make sure that the transition does not violate any transition rules. For plan transitions where there is no /transition object for the transition rule, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN uses the value supplied by you in the output flist from PCM_OP_SUBSCRIPTION_POL_PRE_TRANSITION_ PLAN policy opcode.
3.
Validates the Primary Basic Service (PBS) that must be applied on the plan transition. For plan transitions where there is no /transition object for the transition rule, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN uses the value supplied by you in the output flist from PCM_OP_SUBSCRIPTION_POL_PRE_ TRANSITION_PLAN policy opcode. For:
A regular transition, the two transition plans share a primary service. If not, the transaction fails. For a plan transition that involves a generation change, PCM_OP_ SUBSCRIPTION_TRANSITION_PLAN skips this step because the two plans do not have to share the same primary service.
4.
Handles the non-currency grants in the source plan based on the value of PIN_ FLD_FLAGS input field. If the value of FLD_FLAGS is PIN_SUBS_TRANSITION_ CONTROL_ROLLOVER, the opcode calls a rollover function to ensure, if
11-61
Managing Plans
necessary, that the source plan retains non-currency grants and they are valid to the end of the cycle. To do so, the rollover function checks the plan list for the source and target plans and takes the following action:
If the plans are in the same plan list, the rollover function searches for all the sub-balances that are truncated because of the transition and extends the sub-balances to the original date before the truncation. If the plans are not in the same plan list, this function searches for all the sub-balance buckets that are impacted by the transition and truncates the bucket to the current time.
5.
Acts on the services in the plan-to-plan transition. If any services in the plans are listed as inactive, the transition is aborted.
If PIN_FLD_FROM_SERVICE is NULL or not specified in the flist, the new service in PIN_FLD_TO_SERVICE is added to the account. If PIN_FLD_TO_SERVICE is NULL or not specified, the service specified in PIN_FLD_FROM_SERVICE is closed. If PIN_FLD_FROM_SERVICE and PIN_FLD_TO_SERVICE have non-null values, only the deals are canceled and the deals from PIN_FLD_TO_SERVICE are purchased. Any account-level deals in FROM_PLAN are canceled. Any account-level deals in TO_PLAN are purchased.
6.
For the plan being phased out due to a generation change in the transition, PCM_ OP_SUBSCRIPTION_TRANSITION_PLAN creates a /schedule object that closes the services associated with the plan at 00:00:00 hours at the end of the day of transition. Additionally, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN performs these steps:
Prepares the input flist for the PCM_OP_CUST_UPDATE_SERVICES opcode by specifying the value of END_T as 00:00:00 hours on the following day. For example, if the transition is issued on January 15, 2004, at 12:30:00, the plan being phased out ends at January 16, 2004, at 00:00:00 hours. Calls the PCM_OP_ACT_SCHEDULE_CREATE opcode with the above input flist and the PCM_OP_CUST_MODIFY_CUSTOMER opcode number. On the server side, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN: Provides an option that customizes the end dates, allowing the end date to occur one day later. Allows a Product-End-Delay-For-Plan-Transition delay configuration, which is used if the end dates are not passed. This delay configuration is then applied to the date and time of transition as an offset value.
Note:
7.
Charges any cancellation fees for the old deal and purchase fees for the new deal based on the PIN_FLD_FEE flag (in the /transition object or the custom value provided by you in the output flist from PCM_OP_SUBSCRIPTION_POL_PRE_ TRANSITION_PLAN policy opcode).
Managing Plans
Note:
These fees are always prorated regardless of the products cancellation proration setting.
8.
Creates /event/notification/plan/transition and event/notification/plan/transition_complete notification events. These events are not persistent.
BRM returns the following messages based on the success of failure of the transition:
If the transition is successful, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN returns a message confirming the success. If the transition type is not a generation change and involves two plans that do not share a primary basic service, PCM_OP_SUBSCRIPTION_TRANSITION_PLAN returns the message The PBS does not match from-plan and to-plan. If the transition violates any transition rules, PCM_OP_SUBSCRIPTION_ TRANSITION_PLAN returns the message Plan is not transitionable.
Obtain a list of plans available for transition: Use the PCM_OP_CUST_POL_ TRANSITION_PLANS policy opcode. Customer Center calls this policy opcode to return the list of plans available for transition. This policy opcode takes a plan POID and transition type (usually upgrade or downgrade) as input, reads the /transition object, and returns the list of plans available for transition as output. For more information, see PCM_OP_CUST_ POL_TRANSITION_PLANS in BRM Developer's Reference.
Customize the validation as necessary: This is optional. Use the PCM_OP_ SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode to perform any additional validation checks or filters for transitioning plans. For example, you can restrict a plan transition to customers from a particular location or require that customers own the first plan for a specific period of time before allowing the transition to a different plan.
Provide custom values for service and fees: This action is required if you plan to customize plan transitions without configuring the /transition object. Modify the output flist of the PCM_OP_SUBSCRIPTION_POL_PRE_ TRANSITION_PLAN policy opcode to specify the service that must be associated with the plans and whether to waive purchase and cancellation fees associated with the plans. To do so:
1.
Add the PIN_FLD_RESULTS array to the output flist of the PCM_OP_ SUBSCRIPTION_POL_PRE_TRANSITION_PLAN policy opcode:
0 array RESULTS 1 int FEE_FLAG 1 str PERMITTED
2.
Set the PIN_FLD_FEE_FLAG field in PIN_FLD_RESULTS to one of the values in Table 112:
11-63
Managing Plans
PIN_FLD_FEE_FLAG Values Description Charge cancellation fees for the old product and purchase fees for the new product. Waive purchase fees. Waive cancellation fees. Waive purchase fees and cancellation fees.
Set the PIN_FLD_PERMITTED field of this array to the Primary Basic Service (PBS) that must apply to the plan transition.
For example,
0 PIN_FLD_RESULTS ARRAY [0] allocated 20, used 3 1 PIN_FLD_FEE_FLAG INT [0] 3 1 PIN_FLD_PERMITTED STR [0] "/service/telco/gsm/telephony"
/service/telco/pdc, a 2G service type based on the Personal Digital Cellular (PDC) standard for digital mobile telephony. /service/telco/imt, a 3G service type based on the International Mobile Telecommunications (IMT) standard for 3G wireless communications.
Managing Plans
Important:
When a transition between two plans is under way, no other transition is allowed between the two plans for the duration of the transition day. You can backdate the subscription actions to a prior period in case of a generation change, but doing so can lead to incorrect results.
The New Plan For the plan replacing the current plan, the following happens at 00:00:00 hours at the start of the transition day:
The purchase, cycle, and usage start dates are set to 00:00:00 hours at the beginning of the transition day. All dependent services and deals associated with the plan are included in the transition. Any cycle fees for this plan are charged from 00:00:00 hours at the beginning of the transition day to the end of the billing cycle.
Note: Purchase and cancel fees can be configured to be waived during the transition.
All configured deals are purchased for the service. The new service is provisioned.
The Current Plan For the plan you are phasing out, the following happens at 00:00:00 hours at the end of the transition day:
The current service is closed. Any dependent services are closed. All associated products and dependent services are canceled. Forward and arrears cycle fees are prorated from the beginning of the billing cycle to the cancellation time.
Use the following command to create an editable XML file from the billing instance of the /config/business_params object:
pin_bus_params -r BusParamsBilling bus_params_billing.xml
11-65
This command creates the XML file named bus_params_billing.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.
2.
3.
Change 10 to the number of days you want the phased-out service to remain active (the default is 10 days). For example, if you change the value to 15, the phased-out service remains active 15 days after generation of the new service. The minimum number of days you can keep a phased-out service active is 1 and the maximum is 31.
Caution: BRM uses the XML in this file to overwrite the existing billing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRMs billing configuration.
4. 5.
Save and close the file. Use the following command to load the change into the /config/business_params object:
pin_bus_params bus_params_billing.xml
You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see "pin_bus_params" in BRM Developer's Guide.
6.
Read the object with the testnap utility or Object Browser to verify that all fields are correct. See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.
7. 8.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide. For multiple databases, run the pin_multidb script with the -R CONFIG parameter. For more information on this script, see "pin_multidb" in BRM System Administrator's Guide.
A customer requests a product cancellation on October 30, but the cancellation is not recorded in the BRM system until November 15. The customer is charged for the period of October 30 to November 15.
A customer requests a product purchase on January 1, but the purchase date is entered in the BRM system as February 1.
Backdated account creation. See "About Backdated Account Creation". Backdated account and service status change. See "About Backdated Status Change". Backdated product, discount, deal, or plan purchase. See "About Backdated Product, Discount, Deal, or Plan Purchase". Backdated product, discount, or deal cancellation. See "About Backdated Product, Discount, or Deal Cancellation". Backdated product or discount purchase, usage, or cycle start and end date. See "About backdated purchase, usage, or cycle end dates". Backdated sequential discount purchase, cancellation, and modification if the validity rules are set to Prorated discount. See the discussion of validity rules in the BRM Configuring Pipeline Rating and Discounting.
You can perform subscription backdating by using either of the following methods:
By using Customer Center. Subscription backdating is available only to customer service representatives (CSRs) who have the appropriate permission. Permissioning can be enforced only through Customer Center.
By passing the backdated date in the PIN_FLD_END_T field of the corresponding subscription opcodes.
11-67
You might manually need to rerate the usage events that had been rated prior to the backdating action. For example, on October 15, a usage event for a product is charged at $2.00 per minute. On November 1, a new product is purchased backdated to September 1. The new product has the usage rate of $1.00 per minute and has a higher priority than the first product. In order for the usage that occurred on October 15 to get rated with the new product, you must rerate the usage events manually.
If you backdate the cancellation of a shared discount, you will need to rerate the accounts or services in the group, because the accounts or services might have used the discount.
BRM lets you set up trigger-dependent rerating for the backdating operations. See "Setting up trigger-dependent rerating" in BRM Setting Up Pricing and Rating.
Sets the purchase, usage, and cycle start dates to the backdated date unless they are explicitly set to a different date. Prorates the cycle fee based on the proration settings. Applies the purchase fee on the backdate date.
See "Example of backdated product purchase" and "Example of backdated discount purchase". BRM does not allow you to backdate the product, discount, deal, or plan purchase if:
The backdated purchase date is prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date". The backdated purchase date is prior to the account or services effective date. See "How Effective Time is Used to Validate Backdating Operations". The backdated purchase date is prior to the date of the last status change of the account or service. For example, consider that you create an account on December 1. On December 10, you change the status of the account to Inactive. On December 15, you change the status of the account back to Active. You cannot backdate a product purchase prior to December 15, which is the date of the last status change.
Note:
BRM does not apply a fold, rollover product, or bill time discount for the past accounting cycles when you backdate the purchase of the fold, rollover product, or bill time discount. Backdating discounts with discount validity rules are supported only for discounts that are prorated. For more information about discount validity rules, see "About Applying Discounts Activated or Canceled in Mid-Cycle" in BRM Configuring Pipeline Rating and Discounting.
1800 Anytime Minutes for January 15 to February 1. 3600 Anytime Minutes for February 1 to March 1. 3600 Anytime Minutes resources for March 1 to April 1.
Important:
If you backdate the purchase of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be applied only from the current accounting cycle.
Cycle forward charge of $9.95. Proration set to Charge based on amount used.
$4.97 for the period from September 15 to October 1 (for 15 days). $9.95 for the period from October 1 to November 1. $9.95 for the period from November 1 to December 1.
These charges are included in the next bill that gets generated during the bill run on December 1. This bill also includes the charges that are generated for the period of December 1 to January 1. In the same example, if the product being purchased has cycle arrears fees instead of cycle forward fees, the two cycles until the current cycle are charged as follows:
11-69
These charges will get included in the next bill that gets generated during the bill run on December 1. Example of backdated discount purchase Consider that on April 1, you create an account that owns a product with a cycle forward fee of $50. The cycle fee of $50 for April1 1 to May 1 is applied. On April 16, purchase a discount that applies 10% on the monthly cycle fees, backdated to April 1. A discount of $5 is applied for the period of April 1 to May 1.
If you backdate a discount purchase to a date prior to the product purchase date, the discount will not be applied in the bill of the current cycle. The discount will be applied in the bill of the next cycle.
Important:
If you backdate the purchase of a discount on a cycle forward or cycle arrears event to a previous accounting cycle, the discount will be refunded only for the current accounting cycle.
BRM does not allow you to backdate the product, discount, or deal cancellation if:
The backdated cancellation date is prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date". The backdated cancellation date is prior to the product or discounts effective date. For example, a product or discount that was purchased to be effective from January 15 cannot have any event on it backdated prior to January 15. See "How Effective Time is Used to Validate Backdating Operations". The backdated cancellation date is prior to the date of the last status change of the account or service. For example, consider that you create an account on December 1. On December 10, you change the status of the account to Inactive. On December 15, you change the status of the account back to Active. You cannot backdate a product cancellation prior to December 15, which is the date of the last status change.
Note:
When you backdate the cancellation of a fold, rollover product, or bill time discount, you must run rerating to apply the corrections on the events that occurred after the backdated date. Backdating discounts with discount validity rules are supported only for discounts that are prorated. For more information about discount validity rules, see "About Applying Discounts Activated or Canceled in Mid-Cycle" in BRM Configuring Pipeline Rating and Discounting.
Cycle forward fee $3.00. Proration set to Charge based on amount used.
The three cycles including the current cycle are refunded as follows:
$1.50 for the period of September 15 to October 1 (for 15 days). $3.00 for the period of October 1 to November 1. $3.00 for the period of November 1 to December 1.
These refunds are included in the next bill that gets generated during the bill run on December 1. Example of backdated discount cancellation On April 1, consider that you create an account that owns a product with $50 as a cycle forward fee and a discount of 10% on the monthly cycle fees. A cycle fee of $50 and a discount of $5 is applied for the period of April 1 to May 1, making the balance $45. On April 28, you cancel the discount backdated to April 16. The discount of $2.50 applied for the period of April 16 to May 1 is refunded, making the balance as $47.50.
11-71
For example, on February 15, a product with cycle forward events for an account with the DOM set to 1 is purchased, backdated to January 15. The EARNED_ START_T and EARNED_END_T for the backdated period (January 15 through February 1) will be January 15 and February 1 respectively, while the EARNED_START_T and EARNED_ END_T for the current cycle will be February 1 and March 1 respectively.
PCM_OP_CUST_POL_GET_PLANS. See "Getting Plans, Deals, and Products for Purchase". PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS. See "Getting a List of Deals, Products, Discounts, and Services". PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS. See "Getting a List of Plans and Deals that an Account Owns". PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS. See "Reading Data for All Valid Purchased Products and Discounts". PCM_OP_SUBSCRIPTION_GET_HISTORY. See "Finding Events Associated with Deals, Products, Discounts, and Services".
To get a list of plans for customer purchase, use the PCM_OP_CUST_POL_GET_ PLANS policy opcode. This policy opcode chooses the plans to return based on the AAC fields in the input flist. If the account is new, this policy opcode gets plans from the new plan list. Otherwise, it uses the addon plan list. If it does not find a list, the default plan list is used. You can customize the PCM_OP_CUST_POL_GET_PLANS policy opcode to search the /group/plan_list object by customer type and display the correct plan lists based on the customer type. For information about plan lists, see "About Plan Lists" in BRM Setting Up Pricing and Rating.
To get a list of deals for customer purchase, use the PCM_OP_CUST_POL_GET_ DEALS policy opcode. This policy opcode searches for all /deal objects that are valid (deal END_T = 0 is valid). Each deal in the list is then read and checked to see whether the deals permitteds array allows the storable object type to purchase it.
Use the PCM_OP_CUST_POL_READ_PLAN policy opcode to customize deals during account creation. For a given plan, this policy opcode constructs a tree of services, deals, and products associated with that plan. This policy opcode retrieves account-level plans in addition to plans related to services.
To get a list of products for customer purchase, use the PCM_OP_CUST_POL_ GET_PRODUCTS policy opcode. The products permitteds array is checked for valid storable object types purchasing the product.
Item, canceled, and deleted product and discount instances are not returned if the products or discounts event objects are not recorded or if they are purged. For example, if BRM is configured to not record events with no balance impacts, records for these events are not returned.
PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS gets the purchase, cycle, and usage validity periods for products and discounts from the accounts /purchased_ product and /purchased_discount objects. It returns this information in the purchase, cycle, and usage START_T and END_T fields located in the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays in the output flist. If a product or discount is set to start on first usage and its validity period has not yet been initialized, additional information about the purchase, cycle, and usage start and end times is returned in START_DETAILS and END_DETAILS fields.
The policy opcode returns plans or deals that an account owns. It does not return a plan if the plan has only optional deals. The plan must have at least one purchased deal.
The PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS policy opcode takes an account POID from the input flist and returns a list of all plans, including balance group information and deals the account owns.
11-73
If the account contains optional deals that it does not own, those deals are returned with the list as eligible to purchase (PIN_FLD_BOOLEAN value of 0). The PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS policy opcode can perform additional filtering of plans or deals before they are returned. For example, add filtering logic to this policy opcode to return only inactive optional deals. Plans and deals that were closed during a transition are not added to the output flist.
Caution!:
An account owning more than one instance of a plan is not supported. In this case, this policy opcode returns deals for one of the plans selected at random.
The PCM_OP_CUST_POL_GET_SUBSCRIBED_PLANS policy opcode returns deals in a PIN_FLD_DEALS array, even if it found them listed in the account in the older PIN_ FLD_DEAL_OBJ field.
An /account object: The opcode gets all the products and discounts for the account as well as its services. A /billinfo object: The opcode gets the purchased products and discounts that contribute to the given billinfo. A /service object: The opcode gets the purchased products and discounts that belong to the given service.
The opcode logic performs a search based on the scope object passed in the input flist. Most of the other parameters are filters that work on a particular scope. The input flist would look like this:
0 0 0 0 0 0 0 0 0 0 0 0 PIN_FLD_POID POID [0] 0.0.0.1 /account 618010 0 PIN_FLD_SCOPE_OBJ POID [0] 0.0.0.1 /service/ip 615706 3 PIN_FLD_STATUS_FLAGS INT [0] 3 PIN_FLD_VALIDITY_FLAGS INT [0] 3 PIN_FLD_INCLUSION_FLAGSINT [0] 2 PIN_FLD_OVERRIDE_FLAGS INT [0] 2 PIN_FLD_END_T TSTAMP [0] (1154415600) Tue Aug 1 00:00:00 2006 PIN_FLD_DEAL_OBJ POID [0] 0.0.0.1 /deal 615702 3 PIN_FLD_OVERRIDDEN_OBJ POID [0] 0.0.0.1 /purchased_product 324706 0 PIN_FLD_PACKAGE_ID INT [0] 23 PIN_FLD_PRODUCTS ARRAY [*] NULL array ptr PIN_FLD_DISCOUNTS ARRAY [*] NULL array ptr
The opcode can accept filters to limit the search further. The input for the opcode contains parameters to retrieve the correct set of offerings:
To retrieve only products or only discounts, use the PIN_FLD_PRODUCTS and PIN_FLD_DISCOUNTS arrays. To retrieve only specific fields from the /purchased_product objects, specify the fields in the PRODUCTS and DISCOUNTS arrays.
To retrieve products and discounts with a specific status, pass the PIN_FLD_ STATUS_FLAGS field and specify one of these values: PIN_SUBS_FLG_OFFERING_STATUS_ACTIVE: This flag retrieves only active offerings. PIN_SUBS_FLG_OFFERING_STATUS_INACTIVE: This flag retrieves only inactive offerings. PIN_SUBS_FLG_OFFERING_STATUS_CLOSED: This flag retrieves only closed offerings.
Note:
Use of multiple values implies the target object should satisfy any of the above.
To retrieve products or discounts valid as of a given time, pass the PIN_FLD_ END_T field in the input flist. You can base the end time on only the purchase, cycle, or usage period by including the PIN_FLD_VALIDITY_FLAGS field in the input flist with one or more of these values. PIN_SUBS_FLG_OFFERING_VALIDITY_CYCLE: This flag tells the opcode to compare the END_T value passed to the CYCLE_END_T value. PIN_SUBS_FLG_OFFERING_VALIDITY_PURCHASE: This flag tells the opcode to compare the END_T value passed with PURCHASE_END_T. PIN_SUBS_FLG_OFFERING_VALIDITY_USAGE: This flag tells the opcode to compare the END_T value passed with USAGE_END_T.
Note:
Use of multiple flags implies the target object must satisfy all of the above conditions.
To retrieve all eligible offerings, which include account-level and subscription-level offerings, pass the PIN_FLD_INCLUSION_FLAGS field on the input flist with one or more of these values: PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_PRODS: This flag retrieves all eligible products. PIN_SUBS_FLG_OFFERING_INCLUDE_ALL_ELIGIBLE_DISCS: This flag retrieves all eligible discounts.
Note:
When this field is missing, only eligible offerings from a given scope are returned.
To retrieve only account-level products and discounts, pass the PIN_FLD_ OVERRIDE_FLAGS field set to PIN_SUBS_FLG_OFFERING_ACCT_LEVEL_ ONLY. This flag is valid for /account objects only. To retrieve customized products that override the base product, pass the following two fields in the input flist: PIN_FLD_OVERRIDE_FLAGS field set to PIN_SUBS_FLG_OFFERING_ OVERRIDE_PRODS_ONLY. When a valid product POID is passed in the OVERRIDDEN_OBJ field, this flag returns all the customized products that
11-75
override the specified base product. When a NULL product POID is sent, only the base products are returned. This field is valid for any scope. PIN_FLD_OVERRIDDEN_OBJ set to the POID of the base product that is overridden. This flag searches for all the products that use that base product, including the base product itself. If the OVERRIDDEN_OBJ field is null and the PIN_FLD_OVERRIDE_FLAGS value is set to PIN_SUBS_FLG_ OFFERING_OVERRIDE_PRODS_ONLY, only base products are retrieved.
To retrieve products and discounts for only a single plan, pass the PIN_FLD_ PACKAGE_ID field set to the package ID. This field can be used with any scope. To retrieve products and discounts for a specific deal, pass the PIN_FLD_DEAL_ OBJ field set to the /deal objects POID.
PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS returns all purchased products and discounts, including canceled products and discounts, within the parameters used.
If a deal is specified, a history of all events associated with the specific deal instance is returned for the account. The deal is identified by the PIN_FLD_ PACKAGE_ID field in the input flist. If a product is specified, a history of all events associated with the specific product instance is returned for the account. The product instance is identified by the PIN_ FLD_OFFERING_OBJ field in the input flist. If a discount is specified, a history of all events associated with the specific discount instance is returned for the account. The discount instance is identified by the PIN_FLD_OFFERING_OBJ field in the input flist. If a service is specified, all events associated with that service object are returned for the account.
If you do not specify a date range, PCM_OP_SUBSCRIPTION_GET_HISTORY uses the accounts creation time. If a RESULTS array is passed in the input flist, PCM_OP_SUBSCRIPTION_GET_ HISTORY returns only fields from the events that are passed in the RESULTS array.
Pipeline rate plan data, if the product includes events configured for pipeline rating. Provisioning tag details from the /config/provisioning_tag object or the /config/telco/* object, if a product is configured with a provisioning tag. See "Working With Provisioning Tags" in BRM Setting Up Pricing and Rating.
The opcode searches for the /product object you specify in the input flist. You can specify either the POID of the object or a type-only POID and the product name. The opcode examines each PIN_FLD_USAGE_MAP array in the product information returned by the search. Based on the content of the array, the opcode searches for and retrieves several different types of rating information:
The opcode retrieves the content of all real-time rate plans included in the usage map, as well as the content of the /rate objects included in those rate plans. If a usage map array includes an event to be rated by a pipeline rate plan, the opcode optionally retrieves pipeline rate plan data from the database. You specify whether the opcode retrieves pipeline rate plan data by passing the FM_PRICE_ SUPPRESS_PIPELINE_DATA flag in the opcode call: When the FM_PRICE_SUPPRESS_PIPELINE_DATA flag is set (0x0001) in the opcode call, the opcode retrieves the pipeline rate plan data from the database. When the FM_PRICE_SUPPRESS_PIPELINE_DATA flag is not set (0) in the opcode call, the opcode does not retrieve any pipeline rate plan data.
For more information about passing flags in opcode calls, see "Understanding the PCM API and the PIN Library" in BRM Developer's Guide.
If it includes a /rate_plan_selector object, the opcode retrieves its contents. If it includes a /rollover object, the opcode retrieves its contents.
The opcode returns the product details in the output flist. If the /product object includes a provisioning tag attribute, the opcode performs the following:
For /service/telco/* service types, the opcode retrieves the provisioning tag details from the /config/telco/* object and returns it in the output flists PIN_FLD_ PROVISIONING_TAG_INFO array. For all other service types, the opcode retrieves the provisioning tag details from the /config/provisioning_tag object and returns it in the output flists PIN_FLD_ PROVISIONING_TAG_INFO array.
If the product is customized, the PIN_FLD_TAILORMADE field has the value 1. The PIN_FLD_TAILORMADE_DATA field includes information about customized real-time rates, stored as semicolon-delimited, comma-separated pairs of resources and percentages.
The POID of the base product to be customized. A type-only POID can be used instead if the product name is supplied. The products customized real-time rate plans and rates. The products customized pipeline pricing data, including rate plan versions, rate plan configurations, price models, model selectors, and model selector rule sets. A list of customized pipeline pricing customizations, expressed in string format as semicolon-delimited, comma-separated pairs of resource IDs and percentages. For
11-77
example, 20% discounts on US dollar and minutes resources are represented as USD,-20;MIN,-20. During the creation of a customized product, the opcode does the following:
Retrieves full product and pipeline rate plan details. Applies the percentage increase or decrease specified in the customization to the applicable real-time rates balance impacts. Creates a name for the customized product by prepending the current time in seconds (expressed in hexadecimal) to the base product name. See "About customized product and pipeline pricing component names". For each pipeline rate plan configuration in the input flist, creates copies of price models and model selectors and applies percentage increases or decreases when necessary. Renames customized pipeline pricing components. The code of each component is changed to include a two-letter abbreviation, the current time in milliseconds (expressed in hexadecimal), and a unique integer value. See "About customized product and pipeline pricing component names". Returns an flist for the complete customized /product object, including both original and customized data for both real-time and pipeline rate plans.
You pass the output of this opcode to the PCM_OP_PRICE_SET_PRICE _LIST opcode, which commits the customized /product object to the BRM database. When the opcode is called to modify an existing customized product, the PIN_FLD_ POID and PIN_FLD_NAME fields in the PIN_FLD_PRODUCTS array contain the actual values for the existing customized /product object. The PIN_FLD_TAILORMADE_DATA fields contain the new customization percentages and resources. The opcode updates the current real-time and pipeline rates based on the new percentages. If the changes affect pipeline rate plans that were not previously customized, the opcode creates copies of pricing data that is now required.
A product cannot be canceled if it belongs to a required deal or to a deal that has a dependency relationship. A deal cannot be transitioned if the source service and the target service are not the same service. A deal cannot be transitioned if the associated service is inactive. A deal cannot be transitioned if it is required in the associated plan. A plan cannot be transitioned if the source service and the target service are not the same service or if the service is inactive.
Open the BRM_Home/sys/data/pricing/example/pin_transition_type file in a text editor. Add your custom transition types by using this syntax:
TransitionIDNumber TransitionString
where:
TransitionIDNumber specifies the ID of the transition type. This value will be visible in the /transition object. Your custom ID numbers must be unique and greater than the number 100. However, they need not be in numerical order. TransitionString specifies the transition name that is displayed in Pricing Center.
For example, add the following line to create a custom transition type named RED:
101 3. 4. RED
Save and close the file. Go to the directory in which you saved the pin_transition_type file and enter the following command:
load_transition_type [TransitionTypeFile]
where TransitionTypeFile specifies the name and location of the file that contains your custom transition types. By default, the utility uses the pin_transition_type file in the directory from which you run the utility.
Note:
For more information about the utilitys syntax, see "load_ transition_type".
5.
Your new transition types are loaded into the /config/transition_type object and are displayed in Pricing Center the next time you start it.
Upgrade - number 1
Managing Customers Services and Products 11-79
You could customize a policy opcode to read this object for validation checks.
12
12
When an account is active, the customer can use all active services. When an account is inactive, the customer cannot use any service. Typically, the customer can still use Web administration forms when the account is inactive. For example, if a payment cannot be made because of a credit card verification error, the customer can use the Web administration form to update credit card and address information so the payment can be made.
Note:
Inactivating an account prevents customers from generating usage and cycle balance impacts but does not prevent the account from being charged for bills already due. See "Billing Inactive Accounts".
When an account is closed, the customer cannot use any service. A closed account is normally closed permanently, but you can reactivate it in Customer Center if it was closed by mistake. Closing an account does not delete the account or its service login names and passwords from the BRM database. Because closed accounts are never deleted from the database, there is no time limit on when they can be reactivated.
Important:
account.
You cannot delete closed accounts from a production database, but you can reuse their login names. See "Reusing Login Names and Passwords from Closed Accounts or Canceled Services".
Note:
You can customize what a customer can do when an account is closed or inactive. For example, you can allow customers to view their account status on the Web. The only functional difference between a closed account and an inactive account is that you can enable BRM to activate and inactivate accounts automatically. BRM cannot automatically close an account or automatically activate a closed account.
When you inactivate an account, all the accounts services are inactivated. When you reactivate an inactive account, all the accounts services that were inactivated when the account was inactivated are reactivated. Services that were inactivated independently of the account status are not reactivated. When you close an account, all the accounts services are closed. When you reactivate a closed account, the accounts services are not reactivated.
When you inactivate an account, all the accounts products and discounts are inactivated.
Note:
In Customer Center, the inactivated products and discounts continue to be displayed on the accounts Product tab.
When you reactivate an inactive account, you reactivate all products and discounts that were active when the account was active. Products and discounts that were inactive when the account was active remain inactive. When you close an account, all the accounts products and discounts are canceled.
Note:
In Customer Center, the canceled products and discounts are removed from the accounts Product tab.
When you reactivate a closed account, the accounts products and discounts are not reactivated. To regain the canceled products and discounts, the account must repurchase the deals that contain them.
Reactivating a closed account does not reinstate the canceled products and discounts. To regain the canceled products and discounts, the account must repurchase the deals that contain them.
The backdated date is prior to the G/L posting date. See "About Backdating Beyond the G/L Posting Date". The backdated date is prior to the effective date of the account, service, product or discount. See "How Effective Time is Used to Validate Backdating Operations". The backdated date is prior to the date of the last status change. You can backdate any status change only up to the date the last status change happened; undoing previous status changes is not allowed. For example, consider that you change the status of an account from active to inactive on September 1. On October 1, you cannot backdate a status change to a date prior to September 1.
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 product status change. PCM_OP_CUST_SET_DISCOUNT_STATUS: for backdating the discount status change.
If the product includes a cycle forward rate that allows proration, the unused fee is refunded. If the product includes a cycle arrears rate that allows proration, the used amount is charged.
When you inactivate an account or service, you can set a future date to reactivate the account or service, or you can reactivate the account or service manually. When you close an account or service, you cannot schedule reactivation. Closed accounts and services must be reactivated manually.
Customer Center lists all deferred actions scheduled for an account. From the list, you can cancel an action or execute it immediately. For more information, see "Managing Deferred Actions".
A credit card payment fails because a nonvalid credit card is used. A credit card validation fails, and the item is 30 or more days past due. The account is a child account with a nonpaying bill unit, and the parent account is inactivated.
Note:
By default, account status is not changed when a credit limit is reached. However, also by default, service authorization requires that the credit limit has not been reached, so reaching a credit limit prevents a customer from using a service.
To change these defaults, you must customize the following policy opcodes:
PCM_OP_PYMT_POL_COLLECT PCM_OP_ACT_POL_SPEC_VERIFY
Note:
When you close an account or service, you cannot schedule reactivation. Closed accounts and services must be reactivated manually.
The status of all the parent accounts bill units are changed. The status of every subordinate bill unit in every child account is changed.
Note: The child accounts status and the status of nonsubordinate bill units in child accounts are not changed.
If a subordinate bill unit in a child account is also the parent of another accounts bill units, the status of the subordinate bill units in the other account is also changed.
For more information, see "How Bill Unit Status Changes Affect Hierarchies" in BRM Managing Accounts Receivable. You cannot prevent the status of a nonpaying child bill unit from changing when its parent bill units status changes.
Note:
Changing the account status of a child account does not affect the status of its parent. In a sponsor group, if the sponsor group owner account is inactive, the member accounts receive the balance impacts that normally would have been sponsored.
Reusing Login Names and Passwords from Closed Accounts or Canceled Services
By default, you can not reuse the login name of a closed account or canceled service, although BRM has no restriction on reusing passwords. To reuse login names, set up BRM to automatically modify the login name when you close an account. For example, you could have the string #CLOSED# prepended to the login name.
You can customize the PCM_OP_CUST_POL_PREP_STATUS policy opcode to automatically add characters to a login name when an accounts status changes.
Changing Purchase and Cycle Start Time for Reactivated Products and Discounts
By default, when inactive products and discounts are reactivated, the purchase and cycle start times are changed to the current (reactivation) date.
Note:
The purchase and cycle start times determine the date on which the purchase and cycle charges begin to be applied to the product and discount.
You can use the Connection Manager (CM) configuration file change_start_time_on_ activation entry to change this behavior so that when inactive products and discounts are reactivated, the original purchase and cycle start times are kept. To keep the original purchase and cycle start times:
1. 2.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). BRM_Home is the directory in which you installed the BRM software. Add the following entry:
-fm_bill change_start_time_on_activation 0
0 keeps the original purchase and cycle start times. 1 changes the purchase start time and cycle start time to the reactivation date. This is the default.
3. 4.
Save and close the file. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
0 prohibits active services with inactive accounts. This is the default. 1 allows inactive accounts to have active services.
3. 4.
Save and close the file. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
When the status of an account or service is changed. When a product status is changed. You might need to change only the product status itself if, for example, the product was purchased as inactive because of future provisioning and you activate it later.
Note:
When you change the status of a base product, the opcode automatically changes the status of any associated customized products. You cannot set the status of a customized product directly.
Opens a transaction. Retrieves the new status from the PIN_FLD_STATUSES array in the input flist. If the product status change is due to an account or service status change, PIN_ STATUS_FLAG_DUE_TO_ACCOUNT is passed in the PIN_FLD_STATUS_ FLAGS field of the array. Reads the old status of the product from the database. If PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS is not called in CALC_ ONLY mode, applies the new status to the product. If the product is inactive due to future provisioning and is now being activated, then the PCM_OP_SUBSCRIPTION_SET_PRODINFO opcode is called to modify the purchase start date and time to the date and time of reactivation. If the original cycle and usage start date is earlier than the new purchase start date, PCM_OP_ SUBSCRIPTION_SET_PRODINFO also resets the cycle and usage start date and time to the new purchase start date. For more information, see "Handling Purchase, Cycle, and Usage Start and End Times". If PCM_OP_SUBSCRIPTION_SET_PRODINFO is not called, an /au_purchased_ products audit object is generated, which is used for rerating events.
3. 4. 5.
6.
If PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS is called while activating an account, sets the purchase time to NOW and sets the usage and cycle fees by calling PCM_OP_SUBSCRIPTION_SET_PRODINFO. If the product status change is backdated, validates that:
7.
The date to which the product status change is backdated is not prior to the G/L posting date. The date to which the product status change is backdated is not prior to the account or services effective date. The date to which the product status is backdated is not prior to the last status change of the account or service. See "About Backdated Status Change".
8. 9.
If the PCM_OP_CALC_ONLY flag is set when calling PCM_OP_SUBSCRIPTION_ SET_PRODUCT_STATUS, it returns the entire event flist for the events created as a
Changing Account and Service Status 12-7
Setting Account, Service, and Bill Unit Status by Using Your Custom Application
result of the modification. Otherwise, it returns the event Portal object IDs (POIDs) of all event objects created as a result of the modification.
When the status of the account or service that owns the discount is changed. In this case, the discounts status is changed to the status of the account or service. When the status of a discount is changed from inactive to active.
Validates and sets the new status. The new status cannot be the same as the old status.
Note:
When you change the status of a base product, the opcode automatically changes the status of any associated customized products. You cannot set the status of a customized product directly.
2.
Calls the PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO opcode to reset the /discount objects purchase, cycle, and usage start and end dates.
Note:
If the discount purchase, cycle, and usage start or end dates are already set to a later date, or the CM is configured to not reset dates, the dates are not reset.
3.
If the status change of the discount is backdated, this opcode validates that:
The date to which the discount status change is backdated is not prior to the general ledger (G/L) posting date. The date to which the discount status change is backdated is not prior to the account or service effective date. The date to which the discount status is backdated is not prior to the last status change of the account or service. See "About Backdated Status Change".
4.
Setting Account, Service, and Bill Unit Status by Using Your Custom Application
For information about changing status, see "Changing Account and Service Status". The following opcodes are used to set account, bill unit, and service status:
Setting Account, Service, and Bill Unit Status by Using Your Custom Application
Do not call this opcode directly for service status changes. Call the PCM_OP_CUST_UPDATE_SERVICES opcode instead.
PCM_OP_CUST_POL_PREP_STATUS and PCM_OP_CUST_POL_VALID_ STATUS. See "Customizing Status Changes". PCM_OP_ACT_POL_EVENT_LIMIT. See "Inactivating Accounts that Exceed a Specified Limit".
Triggers auto-billing if bills are still pending. See "About Auto-Triggered Billing" in BRM Configuring and Running Billing. 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 subordinate 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 storable object is created to record details of the operation.
Setting Account, Service, and Bill Unit Status by Using Your Custom Application
Table 121
PIN_FLD_STATUS Values Description Account or bill unit fully functional; login is subject to credit limit check. Inactive account or bill unit; no logins permitted and no fees are charged. Closes the account or bill unit, which can be reopened later. This does not activate the corresponding products. Reserved for BRM. PIN_ERR_BAD_ARG is returned if you try to set a status to this value. Value 10100 10102 10103
PIN_STATUS_DEFUNCT
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.
Setting Account, Service, and Bill Unit Status by Using Your Custom Application
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. See "Executing Deferred Actions With the pin_deferred_act Utility" in BRM Configuring and Running Billing.
Deferred Actions
For deferred actions, the PIN_FLD_WHEN_T field is passed to indicate the date on which the status change will be 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, execute, and modify /schedule objects using Customer Center or by calling the opcodes in Table 123:
Table 123 Opcode PCM_OP_ACT_SCHEDULE_CREATE PCM_OP_ACT_SCHEDULE_DELETE PCM_OP_ACT_SCHEDULE_MODIFY PCM_OP_ACT_SCHEDULE_EXECUTE Opcodes used to Modify /schedule Objects Function Creates a schedule object. Deletes a schedule object. Modifies a schedule object. Executes a schedule object.
By default, the pin_deferred_act utility, which is part of the pin_bill_day billing script, finds expired schedule objects and calls the PCM_OP_ACT_SCHEDULE_ EXECUTE opcode, 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.
To customize the way status is changed, use the PCM_OP_CUST_POL_PREP_ STATUS policy opcode. The default implementation does nothing. To validate status changes, use the PCM_OP_CUST_POL_VALID_STATUS policy opcode. The default is to do no additional checking and to return the verified information. For example, you can use this policy opcode to customize how customer service representatives (CSR) can set permissions on specific service types.
See "About the PREP and VALID Opcodes" in BRM Developer's Guide.
Calls PCM_OP_CUST_SET_STATUS to inactivate an account or account hierarchy based on the status set in the PIN_FLD_STATUS field. Calls the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode to notify any custom applications that a limit was reached and that an action took place.
Changing the status of an account or service. Adding an account to a hierarchical group. Removing an account from a hierarchical group. Moving an account between hierarchical groups.
After an action is deferred, you can display, execute, reschedule, and cancel the deferred action. To execute deferred actions automatically on their scheduled date, you can use a daily billing utility, pin_deferred_act. See "Executing Deferred Actions With the pin_ deferred_act Utility" in BRM Configuring and Running Billing.
All actions whose execution date is in the future. The status of these actions is Pending. Any actions that could not be executed on their scheduled date and have not been deleted from the Deferral Details table. The status of these actions is Error. Any completed actions that have not been deleted from the Deferral Details table. The status of these actions is Done.
The number of deferred actions scheduled for each service owned by an account is shown in the Deferred Actions column of the table on the Service tab.
PCM_OP_ACT_SCHEDULE_CREATE. See "Scheduling Deferred Actions". PCM_OP_ACT_SCHEDULE_MODIFY. See "Modifying Deferred Action Descriptions". PCM_OP_ACT_SCHEDULE_DELETE. See "Deleting Deferred Actions". PCM_OP_ACT_SCHEDULE_EXECUTE. See "Executing Deferred Actions". PCM_OP_ACT_POL_VALIDATE_SCHEDULE. See "Performing Policy Checks before Scheduling 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 the PCM_OP_ACT_POL_ EVENT_NOTIFY policy opcode or the PCM_OP_BILL_GROUP_MOVE_MEMBER opcode.
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 the PCM_OP_ACT_SCHEDULE_EXECUTE opcode executes 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.
Delete the /schedule object by using the PCM_OP_ACT_SCHEDULE_DELETE opcode. See "Deleting Deferred Actions". Re-create the /schedule object by using PCM_OP_ACT_SCHEDULE_CREATE. See "Scheduling Deferred Actions".
Execute the action defined in the /schedule object. Update PIN_FLD_STATUS to either Done or Error, depending on its success.
13
Managing Service Life Cycles
31
This chapter describes how to use the Service Lifecycle Management (SLM) feature to configure and use custom service life cycles in Oracle Communications Billing and Revenue Management (BRM).
Active: The customer can perform normal service activity. Inactive: The customer's use of the service is restricted, usually because a credit limit was exceeded, a bill was not paid, or the service is new and is waiting for provisioning. This is a temporary status. Closed: The customer is prevented from using any aspect of the service. This status implies that the customer will not use the service again.
You cannot customize the default service life cycle. If you need a life cycle that better represents the phases of a particular service type, create a custom service life cycle for that service type. BRM includes a sample prepaid service life cycle that has the following states:
Preactive: This is the start state of the sample prepaid service life cycle. The subscriber has not yet used the service. Active: The subscriber can perform normal service activity. Recharge Only: The subscriber can receive calls and use free aspects of the service, but she cannot make prepaid calls. She can use top-ups to replenish the balance. Credit Expired: The subscriber cannot make or receive calls. Dormant: A dormant service has the same available features as an active service. If a subscriber uses a dormant service, its state automatically changes to Active. Fraud Investigated: The service's account is being examined for evidence of fraudulent activity. The subscriber cannot make or receive calls. Suspended: The subscriber intends to resume the service. In this state, no aspect of the service can be used. Closed: This is the final state of the prepaid service life cycle. In this state, no aspect of the service can be used.
See "About the Sample Prepaid Service Life Cycle" for more information. Custom service life cycles can contain any number of states and state transitions. For each state, you can specify the following:
A descriptive name An expiration time Rules to validate requests received in the state The states to which the state can change The actions that occur before and after a state transition takes place
You can associate custom life cycles with any BRM service type. The default service life cycle status is stored in the PIN_FLD_ STATUS field in /service objects. The custom service life cycle state is stored in the PIN_FLD_LIFECYCLE_STATE field of /service objects.
Note:
Enable the SLM feature. See "Enabling BRM to Use Custom Service Life Cycles". Enable the load_config utility to validate SLM configuration files. See "Enabling load_config to Validate SLM Configuration Files". Add SLM entries to the Connection Manager (CM) pin.conf file. See "Adding SLM Entries to the CM pin.conf File".
2. 3. 4. 5. 6.
Create a custom service life cycle. See "About Creating Custom Service Life Cycles". Map each state in the custom service life cycle to a status in the default service life cycle. See "About Mapping States to Statuses". Associate one or more services with the custom service life cycle. See "About Associating Services with Custom Life Cycles". Associate account bill units with the SLM business profile. See "Associating Bill Units with the SLM Business Profile". Enable Services Framework AAA Manager to validate AAA requests for services that use the custom life cycle. See "Validating AAA Requests for Services that Use Custom Life Cycles". Configure Customer Center to display the names of the custom service life cycle states. See "Configuring Customer Center to Display Custom Service Life Cycle States".
7.
Enable the SLM feature. See "Enabling BRM to Use Custom Service Life Cycles".
Add the SLM validation entry to the load_config pin.conf file. See "Enabling load_config to Validate SLM Configuration Files". Add entries for custom service life cycles to the CM pin.conf file. See "Adding SLM Entries to the CM pin.conf File".
Go to the BRM_Home/sys/data/config directory, where BRM_Home is the directory in which you installed the BRM software. Create an editable XML file for the customer parameter class by using the following command:
pin_bus_params -r -c "Customer" bus_params_customer.xml
BRM creates the bus_params_customer.xml.out file in your working directory. To create this file in a different directory, include the full path in the file name.
3.
In the BusParamsCustomer section of the new file, set the value of the SubscriberLifeCycle parameter to enabled:
<BusParamsCustomer> <SubscriberLifeCycle>enabled</SubscriberLifeCycle> </BusParamsCustomer>
Caution: BRM uses the XML in this file to overwrite the existing /config/business_params object.
If you delete or modify any other parameters in the file, the changes affect the associated functionality of the BRM customer configuration.
4. 5.
Save the updated file as bus_params_customer.xml. Run the following command, which loads the changes into the /config/business_ params object in the BRM database:
pin_bus_params bus_params_customer.xml
Run this command from the BRM_Home/sys/data/config directory, which includes support files used by the pin_bus_params utility. To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.
6.
Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
7.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Managing Service Life Cycles 13-3
Custom service life cycles configured in the config_lifecycle_states.xml file. See "About Creating Custom Service Life Cycles" for more information. Mapping between custom service life cycle states and the default service life cycle statuses configured in the config_service_state_map.xml file. See "About Mapping States to Statuses" for more information.
To validate those XML files, load_config needs the following entry in its pin.conf file:
- load_config validation_module libLoadValidSLM LoadValidSLM_init
If that entry is not in the utilitys pin.conf file, add it before using the utility to load the XML files.
Note: The pin.conf file is in the directory from which the utility is run. The utility is located in BRM_Home/apps/load_config. See "load_ config" for more information.
If these entries are not in your CM pin.conf file, you must add them. To add the CM pin.conf entries for custom service life cycles:
1. 2.
Open the CM pin.conf file in BRM_Home/sys/cm. Add the following entries to the pin.conf file:
- cm_cache hash_size - cm_cache - cm_cache size - cm_cache size fm_bill_utils_business_profile_cache number_of_entries, cache_size, fm_bill_template_cache number_of_entries, cache_size, hash_size fm_cust_lifecycle_config_cache number_of_entries, cache_size, hash_ fm_cust_statemap_config_cache number_of_entries, cache_size, hash_
Where
number_of_entries is the following: For fm_bill_utils_business_profile_cache, the total number of business profiles (/config/business_profile objects), including service life cycle business profiles, that you plan to create in your system. See "About Associating Services with Custom Life Cycles" for more information. For fm_bill_template_cache, the total number of service validation templates (/config/template/service objects), including those defined in service life cycle business profiles, that you plan to create in your system.
See "About Associating Services with Custom Life Cycles" for more information. For fm_cust_lifecycle_config_cache, the number of /config/lifecycle_ states objects you plan to create in your system. Each object represents one custom service life cycle. See "About Creating Custom Service Life Cycles" for more information. For fm_cust_statemap_config_cache, the number of /config/service_ state_map objects you plan to create in your system. The only valid value is 1. See "About Mapping States to Statuses" for more information.
cache_size is the sum of the sizes of the cached objects in bytes. hash_size is the square root of number_of_entries.
For example, if the only custom life cycle you use is the sample prepaid service life cycle and the only business profile you use is the default SLM business profile and its three service validation templates, Oracle recommends the following settings:
3. 4. cm_cache cm_cache cm_cache cm_cache fm_bill_utils_business_profile_cache 1, 12040, 1 fm_bill_template_cache 3, 10240, 1 fm_cust_lifecycle_config_cache 1, 102400, 1 fm_cust_statemap_config_cache 1, 102400, 1
Save and close the file. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
The config_lifecycle_states.xml file can contain multiple service life cycle configurations. In the XML file, each life cycle configuration is identified by its <NAME> element. When the content of the XML file is loaded into the BRM database, each life cycle configuration is put into a separate /config/lifecycle_states object. The objects are distinguished by their Portal object IDs (POIDs).
CSRs: Using Customer Center, a customer service representative (CSR) can manually perform any permitted state change. Such changes are defined in the
<TRANSITIONS> child element of the <STATES> element in the config_ lifecycle_states.xml file (see "About the Service Life Cycle Configuration File" for more information). Customer Center does not allow CSRs to make unauthorized state changes. See the Customer Center Help for more information.
The first use of a service: Services that use the sample prepaid service life cycle start in the Preactive state. The first use of such services triggers the PCM_OP_ TCF_AAA_VALIDATE_LIFECYCLE helper opcode to change the state from Preactive to Active. Any action that impacts a service balance: After a balance is adjusted or topped up, the PCM_OP_BAL_POL_CHECK_LIFECYCLE_STATE policy opcode triggers any required service state changes and updates the state expiration date (PIN_ FLD_SERVICE_STATE_EXPIRATION_T field) in the /service object based on the new states expiration period. For example, this policy opcode supports the sample prepaid service life cycle as follows: If the service state is Active and a balance impact causes the resources associated with the service to reach their credit limit, this policy opcode calls the PCM_OP_CUST_UPDATE_SERVICES opcode, which calls the PCM_OP_ CUST_SET_STATUS opcode to change the state to Recharge Only. The state expiration time in the /service object is not updated. If the service state is Recharge Only or Credit Expired and a balance impact replenishes the associated resources, this policy opcode calls the same opcodes to change the state to Active. If the service state is Preactive, Active, or Credit Expired and a voucher is used to replenish the balance, this policy opcode compares the voucher's validity period with the state's expiration period. It then updates the state expiration date in the /service object based on the greater of the two periods.
Note:
If you create your own custom service life cycles, you can modify this policy opcode to trigger state changes based on different criteria.
pin_state_change: This utility performs bulk service state changes based on the state expiration time (PIN_FLD_SERVICE_STATE_EXPIRATION_T field) in /service objects). A system administrator schedules the utility to run at a specified time each day. When the utility finds services whose state expires on the current date, it changes that state to its default next state.
Note:
The default next state is specified in the <TRANSITIONS> element whose <DEFAULT_FLAG> is set to 1 (see "About the Service Life Cycle Configuration File"). If this flag is not set to 1 in any of the transitions configured for a state, this utility does not change the state.
For example, pin_state_change supports the sample prepaid service life cycle as follows:
When a service is in the Active state and it reaches its state expiration date, the utility changes the state to Recharge Only. When a service is in the Recharge Only state and its balance is not replenished by the states expiration date, the utility changes the state to Credit Expired. When a service is in the Credit Expired state and its balance is not replenished by the states expiration date, the utility changes the state to Suspended.
See "pin_state_change" for more information. See "About Triggering Sample Prepaid State Changes" for more information. See "Changing Account and Service Status" for information about how service status changes are triggered.
<MODULE>: The name of the facilities module (FM) that uses the rule. (The rule is coded in the FM.) For example, the business rules in the sample prepaid service life cycle are used by the AAA module. In that module, the PCM_OP_TCF_AAA_VALIDATE_ LIFECYCLE and PCM_OP_TCF_AAA_POL_VALIDATE_LIFECYCLE opcodes evaluate each request against the business rules configured for the service's current state and authorize or reject the request based on those rules.
<NAME>: The name of the rule as it appears in the FM. <VALUE>: A value that indicates whether the business rule is enabled or disabled for the state.
Code the validation logic for the new rule in the appropriate policy opcode. Include a name for the rule in the policy opcode. Configure a <RULES> element for the rule in the appropriate service life cycle state. See "Creating Custom Service Life Cycles" for more information.
See "About the Sample Business Rules" for more information about the business rules in the sample prepaid service life cycle.
Open the config_lifecycle_states.xml file in an XML editor or a text editor. By default, the file is in the BRM_Home/sys/data/config directory.
2.
3. 4. 5.
In the <ConfigObject> element, specify values for the elements listed in Table 131, " Custom Service Life Cycle Elements". Save and close the file. Run the following command, which loads the config_lifecycle_states.xml file:
load_config config_lifecycle_states.xml
Important:
The "load_config" utility needs a configuration (pin.conf) file in the directory from which you run the utility. The pin.conf file must contain the following entry:
- load_config validation_module libLoadValidSLM LoadValidSLM_ init
This entry enables the utility to validate the XML file values.
If you do not run the utility from the directory in which the configuration file is located, include the complete path to the file. For example:
load_config BRM_Home/sys/data/config/config_lifecycle_ states.xml
The utility converts the XML file into one or more /config/lifecycle_states objects, depending on the number of <ConfigObject> elements in the XML file. Each object contains the life cycle defined in one <ConfigObject> element.
6.
Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
7.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
<STATE_ID>StateID</STATE_ID> <STATE_NAME>StateName</STATE_NAME> <RULES elem="0"> <MODULE>Module</MODULE> <NAME>Name</NAME> <VALUE>Value</VALUE> </RULES> <TRANSITIONS elem="0"> <DEFAULT_FLAG>DefaultFlag</DEFAULT_FLAG> <NEXT_STATE>NextState</NEXT_STATE> <POST_OPCODE>PostOpcode</POST_OPCODE> <PRE_OPCODE>PreOpcode</PRE_OPCODE> </TRANSITIONS> </STATES> </ConfigObject>
NAME
If you configure multiple <PERMITTED_ SERVICE_TYPES> elements, the integer value of each elements elem attribute must be different. The values do not have to be sequential, and they have no relationship to the values of the elem attributes of other elements. Note: The array is included for your convenience. It is not used in the validation process, and it does not associate services with this life cycle. See "About Associating Services with Custom Life Cycles" for more information.
SERVICE_TYPE
Character string that specifies a service type in the PIN_FLD_PERMITTED_SERVICE_ TYPES array.
Specify any service type in your BRM system, such as /service/telco/gsm/telephony. Minimum length is 1 character. Maximum length is 255 characters.
STATES
Parent element of the child elements that define a state for this life cycle. This element is mapped to the PIN_FLD_ STATES array in the /config/lifecycle_states object. The array contains all the states configured for this life cycle.
If you configure multiple <STATES> elements, the integer value of each elements elem attribute must be different. The values do not have to be sequential, and they have no relationship to the values of the elem attributes of other elements.
Table 131 (Cont.) Custom Service Life Cycle Elements XML Element INITIAL_STATE Description Integer that specifies whether this is the initial state of the life cycle. Notes Specify one of the following values:
1: Initial state. Only one state in the life cycle can have this value. 0: Not the initial state.
SERVICE_STATE_ EXPIRATION_T
Character string that specifies the number of days, hours, and minutes between the time the service changes to this state and the time it automatically changes to the default next state in its life cycle.
days days:hrs
BRM uses the state's start date (PIN_FLD_ days:hrs:mins LAST_STATUS_T field of the /service Where object) and the amount of time specified in this element to set the state's end date (PIN_ days is the number of days. FLD_STATE_EXPIRATION_T field of the hrs is the number of hours. /service object). mins is the number of minutes. For example, 365:0:600 specifies 365 days, 0 hours, and 600 minutes. There are no minimum or maximum numbers for this value. STATE_ID Integer that identifies a state in a custom service life cycle. Use 109 or greater for any custom states that you create. Each state ID must be unique. The sample prepaid service life cycle uses the following state IDs:
101: Preactive 102: Active 103: Recharge Only 104: Credit Expired 105: Dormant 106: Fraud Investigated 107: Suspended 108: Closed
See "About the Sample Prepaid Service Life Cycle" for more information about these states. STATE_NAME Character string used as the name of the state (for example, Active). This string is mapped to the PIN_FLD_ STATE_NAME field in the /config/lifecycle_states object. Minimum length is 1 character. Maximum length is 255 characters. Note: Values in this field are used to populate a list of service states in the Change state to field on the Change Account/Service Status panel in Customer Center. They also appear in the Current state field on that panel and in the Status column in the Services tab. When creating the string, take Customer Center UI length restrictions into consideration.
Table 131 (Cont.) Custom Service Life Cycle Elements XML Element RULES Description Parent element of the child elements that define a business rule for this state. This element is mapped to the PIN_FLD_ RULES array in the /config/lifecycle_states object. The array contains all the business rules configured for this life cycle state. The rules validate the actions that subscribers try to perform in the state. For example, the rules configured for the Recharge Only state in the sample prepaid service life cycle permit subscribers to receive calls and to use free aspects of the service, but they do not permit subscribers to make prepaid calls. See "About Configuring Business Rules for Custom Service Life Cycles" and "About the Sample Business Rules" for more information. MODULE Character string that identifies the facilities module (FM) that validates this rule. For example, the AAA module validates the rules configured for the sample prepaid service life cycle. NAME Character string used as the name of the business rule (for example, REQ_ ALLOWED). Note: The rule is coded in an FM. VALUE Character string that specifies whether the rule is enabled or disabled. Use any string that identifies the validating FM. This string is only informational. It does not appear in the code. Minimum length is 1 character. Maximum length is 255 characters. Use a string that matches the name of the rule as it is coded in the FM. Minimum length is 1 character. Maximum length is 255 characters. Specify one of the following values:
Notes If you configure multiple <RULES> elements, the integer value of each elements elem attribute must be different. The values do not have to be sequential, and they have no relationship to the values of the elem attributes of other elements.
TRANSITIONS
Parent element of the child elements that define how this state changes to another state. This element is mapped to the PIN_FLD_ TRANSITIONS array in the /config/lifecycle_states object. The array contains all the states to which this state can change. If a state is not listed in the array, the current state cannot be changed to it. For information about how transitions are triggered, see "About Triggering State Changes in Custom Service Life Cycles".
If you configure multiple <TRANSITIONS> elements, the integer value of each elements elem attribute must be different. The values do not have to be sequential, and they have no relationship to the values of the elem attributes of other elements.
DEFAULT_FLAG
Integer that indicates whether this is the default transition for this state. When the pin_state_change utility changes a service state, it uses the PIN_FLD_NEXT_ STATE whose PIN_FLD_DEFAULT_FLAG is set to 1 in the PIN_FLD_TRANSITIONS array.
1: Default transition. Only one transition for the state can have this value. 0: Not the default transition.
NEXT_STATE
Table 131 (Cont.) Custom Service Life Cycle Elements XML Element POST_OPCODE Description Integer that identifies the policy opcode you want BRM to call after the state transition occurs. In this policy opcode, you must code the action to perform immediately after a state transition occurs. For example, you might add logic to the policy opcode that notifies the subscriber to let her know that her balance is insufficient and needs to be replenished. PRE_OPCODE Integer that identifies the policy opcode you want BRM to call before the state transition occurs. In this policy opcode, you must code the action to perform immediately before a state transition occurs. For example, you might add logic to the policy opcode that notifies the subscriber to let her know that her balance is insufficient and needs to be replenished. Notes Specify the opcode number of the policy opcode to run. Opcode numbers are listed in the pcm_ops.h file in BRM_Home/include directory. Enter 0 to call no opcode.
Specify the opcode number of the policy opcode to run. Opcode numbers are listed in the pcm_ops.h file in BRM_Home/include directory. Enter 0 to call no opcode.
Open the config_lifecycle_states.xml file in an XML editor or a text editor. By default, the file is in the BRM_Home/sys/data/config directory.
2.
For details about editing and loading pin_slm_business_profile.xml, see "Associating Services with Custom Life Cycles". See Table 131, " Custom Service Life Cycle Elements" for more information about the elements of a custom service life cycle.
3.
Set the configMode attribute of the <ObjectList> element to one of the following values:
replace: (Default) Updates the existing /config/lifecycle_states objects. recreate: Deletes the existing /config/lifecycle_states objects and creates new objects.
4. 5.
Save and close the file. Run the following command, which loads the modified config_lifecycle_ states.xml file:
load_config config_lifecycle_states.xml
Important:
The "load_config" utility needs a configuration (pin.conf) file in the directory from which you run the utility. The pin.conf file must contain the following entry:
- load_config validation_module libLoadValidSLM LoadValidSLM_ init
This entry enables the utility to validate the XML file values.
If you do not run the utility from the directory in which the configuration file is located, include the complete path to the file. For example:
load_config BRM_Home/sys/data/config/config_lifecycle_ states.xml
The utility converts the XML file into one or more /config/lifecycle_states objects, depending on the number of <ConfigObject> elements in the XML file. Each object contains the life cycle defined in one <ConfigObject> element.
6.
Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
7.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
WARNING: Do not delete a life cycle that a service is using. Doing so will cause data corruption.
This command deletes all instances of the /config/lifecycle_states class from your BRM database. See "load_config" for more information.
Backward compatibility Custom service state changes triggered by account status changes
Managing Service Life Cycles 13-13
You should not include both services that use the default service life cycle and services that use a custom service life cycle in a subscription group. If you do, the subscription service might be inactive while a member service is active.
A state can be mapped to only one status. A status can be mapped to multiple states. To create state-to-status mapping for the states in all your custom service life cycles, edit the service state mapping configuration file (BRM_Home/sys/data/config/config_ service_state_map.xml). See "About the Service State Mapping Configuration File" for more information. By default, that file contains mapping for the sample prepaid service life cycle, which you can use as is, modify, or delete. See "About the Sample Service State-to-Status Mapping" for more information. After editing the configuration file, use the load_config utility to load the file's contents into the /config/service_state_map object in the BRM database. That object contains the state-to-status mapping for every custom service life cycle in your system. See "Mapping States to Statuses" for more information.
BRM needs a state for a service that uses a custom life cycle. Only the service status is known. The status is mapped to multiple states.
In this situation, BRM uses the statuss default state, which is the state whose PIN_ FLD_DEFAULT_FLAG field is set to 1 for that status in the /config/service_state_map object. For example, suppose the Active (10100) status is mapped to the Active, Recharge Only, and Credit Expired states. If a state value is required for a service whose status (Active) is known but whose state is unknown, BRM uses the state in the PIN_FLD_ STATES array of the /config/service_state_map object that contains the following values:
When a status is mapped to multiple states, the default flag of only one of those states can be set to 1.
The states shown in Table 132 are configured as the status defaults for the sample prepaid service life cycle:
Default States for Statuses in the Sample Prepaid Service Life Cycle Default State Active Suspended Closed
Important:
Every service life cycle state defined in your system must have a transition to each status's default state. This enables BRM to complete a state transition when only the status to which the service must change is known. For example, if BRM receives a request to change a status from Active to Inactive and the current state of the service is Recharge Only, a transition from Recharge Only to Suspended (the default state for the Inactive status) must exist. If the transition is not defined, the transaction fails. The sample prepaid service life cycle has two states that are exceptions to this rule: Preactive (the start state) and Closed (the end state). State transitions are defined in the config_lifecycle_states.xml file. See "Creating Custom Service Life Cycles" for more information.
A custom life cycle state should not be mapped to more than one status. Each status, however, can be mapped to multiple states.
Open the config_service_state_map.xml file in an XML editor or a text editor. By default, the file is in the BRM_Home/sys/data/config directory.
2. 3. 4. 5.
Add a <States> element to the <ConfigObject> element. In the <ConfigObject> element, specify values for the elements listed in Table 133, " Service State Mapping Elements". Save and close the file. Run the following command, which loads the changes into the /config/service_ state_map object in the BRM database:
load_config config_service_state_map.xml
Important:
The "load_config" utility needs a configuration (pin.conf) file in the directory from which you run the utility. The pin.conf file must contain the following entry:
- load_config validation_module libLoadValidSLM LoadValidSLM_ init
This entry enables the utility to validate the XML file values.
If you do not run the utility from the directory in which the configuration file is located, include the complete path to the file. For example:
load_config BRM_Home/sys/data/config/config_service_state_ map.xml
The utility converts the XML file into one /config/service_state_map object.
6.
Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
7.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Table 133
Service State Mapping Elements Description (Optional) Character string that describes the state-to-status mapping. Character string used as the name of the mapping. Notes Minimum length is 0 characters. Maximum length is 255 characters. The name must be unique within your BRM system. Minimum length is 1 character. Maximum length is 255 characters.
NAME
STATES
Parent element of the child elements that map a state to a status. This element is mapped to the PIN_FLD_ STATES array in the /config/service_state_ map object. The array must contain all the the service life cycle states in your system. It can contain states from multiple service life cycles. See "About Mapping States to Statuses".
If you configure multiple <STATES> elements, the integer value of each elements elem attribute must be different. The values do not have to be sequential, and they have no relationship to the values of the elem attributes of other elements.
DEFAULT_FLAG
Integer that specifies whether this is the default state for the status to which it is mapped. A status can be mapped to multiple states, but only one of those states can be the statuss default state. If a state is required when only a status value is available, BRM uses the default state for that status.
1: Default state. If multiple states are mapped to a status, only one of those states can have this value. 0: Not the default state.
LIFECYCLE_STATE
Specify the unique ID of the custom service state to which this mapping applies. This ID is configured in the config_ lifecycle_states.xml file (see Table 131, " Custom Service Life Cycle Elements"). The sample prepaid service life cycle uses the following state IDs:
101: Preactive 102: Active 103: Recharge Only 104: Credit Expired 105: Dormant 106: Fraud Investigated 107: Suspended 108: Closed
See "About the Sample Prepaid Service Life Cycle" for more information about these states. STATUS Integer that specifies the numeric ID of the status in the default service life cycle to which this mapping applies. Specify one of the following status IDs:
Table 133 (Cont.) Service State Mapping Elements XML Element STATUS_FLAGS Description Integer that specifies the status flag to pass when a state change occurs. The status flag specifies the reason for the change. Notes When a service is reactivated, the value must match the value used in the previous state change. Note: STATUS_FLAGS values are listed in the BRM_Home/include/pin_cust.h file.
Open the config_service_state_map.xml file in an XML editor or a text editor. By default, the file is in the BRM_Home/sys/data/config directory.
2.
Modify the <States> element in which the mapping is configured. See Table 133, " Service State Mapping Elements" for more information about the elements of state-to-status mapping.
3.
Set the configMode attribute of the <ObjectList> element to one of the following values:
replace: (Default) Updates the existing /config/service_state_map objects. recreate: Deletes the existing /config/service_state_map objects and creates new objects.
4. 5.
Save and close the file. Run the following command, which loads the changes into the /config/service_ state_map object in the BRM database:
load_config config_service_state_map.xml
Important:
The "load_config" utility needs a configuration (pin.conf) file in the directory from which you run the utility. The pin.conf file must contain the following entry:
- load_config validation_module libLoadValidSLM LoadValidSLM_ init
This entry enables the utility to validate the XML file values.
If you do not run the utility from the directory in which the configuration file is located, include the complete path to the file. For example:
load_config BRM_Home/sys/data/config/config_service_state_ map.xml
The utility converts the XML file into one /config/service_state_map object.
6.
Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct.
For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
7.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
WARNING: Do not delete mapping that a service is using. Doing so will cause data corruption.
This command deletes the /config/service_state_map object from your BRM database. See "load_config" for more information.
Key: lifecycle_obj Value: Name of the custom service life cycle (see Table 131, " Custom Service Life Cycle Elements")
The SLM business profile is configured in the pin_slm_business_profile.xml file. By default, it associates the /service/telco/gsm/telephony service type with the sample prepaid service life cycle (see "About the Sample Prepaid Service Life Cycle").
WARNING: After a service type is in use in your BRM system, do not associate it with a different life cycle. If you do, state and status changes might fail and data might be corrupted.
For example, if subscribers begin purchasing the /service/telco/gsm/telephony service when it uses the default life cycle (Active, Inactive, Closed), do not later associate it with the sample prepaid life cycle. See "Associating Services with Custom Life Cycles" for information about editing the SLM business profile and loading it into the BRM database. See "Managing Business Profiles" for general information about business profiles.
In the list of validation template IDs (<TemplateID> elements), add or delete the name and type of the validation template for the appropriate service. By default, this business profile contains these validation template IDs:
<TemplateId name="ServiceTelcoGprs" type="/service/telco/gprs" /> <TemplateId name="ServiceTelcoGsm" type="/service/telco/gsm" /> <TemplateId name="ServiceTelcoGsmTel" type="/service/telco/gsm/telephony" />
See "Defining Business Profiles" for more information about <TemplateID> elements.
3.
In the list of key values (<NameValue> elements), add or delete key-value pairs to identify the bill units (/billinfo objects) that belong to this business profile. By default, these key values are associated with this business profile:
<NameValue key="Prepaid" value="yes" /> <NameValue key="CacheResidency" value="REALTIME" />
See "Defining Business Profiles" for more information about <NameValue> elements.
4.
In the list of validation templates (<TemplateList> parent element), add or delete the definition of the validation template (<Template> element) for the appropriate service. By default, these validation templates are defined in the SLM business profile:
<TemplateList> <Template name="ServiceTelcoGprs" type="/service/telco/gprs"> <Desc>Description of the template</Desc> <Iscript /> <NameValue key="Prepaid" value="yes" /> <NameValue key="CacheResidency" value="REALTIME" /> </Template> <Template name="ServiceTelcoGsm" type="/service/telco/gsm"> <Desc>Description of the template</Desc> <Iscript /> <NameValue key="Prepaid" value="yes" /> <NameValue key="CacheResidency" value="REALTIME" /> </Template> <Template name="ServiceTelcoGsmTel" type="/service/telco/gsm/ telephony"> <Desc>Description of the template</Desc> <Iscript /> <NameValue key="Prepaid" value="yes" /> <NameValue key="CacheResidency" value="REALTIME" /> <NameValue key="lifecycle_obj" value="Default Lifecycle Configuration" /> </Template> </TemplateList>
Note:
In the ServiceTelcoGsmTel template definition, the following key-value pair associates the /service/telco/gsm/telephony service with the sample prepaid service life cycle: key = lifecycle_obj value = Default Lifecycle Configuration (the NAME value of the sample prepaid service life cycle in the default config_lifecycle_ states.xml file)
See "About Associating Services with Custom Life Cycles". See "Defining Validation Templates" for more information about the <TemplateList> and <Template> elements.
5. 6.
Save and close the file. Create a /config/template/service subclass for each service type in the list of validation template IDs (<TemplateID> elements) of the slm_business_ profile.xml file. For example, to support the SLM business profile, create the following subclasses:
"Creating Service and Event Storable Classes" in BRM Developer's Guide "About Validation Templates"
7.
Run the following command, which loads the SLM business profile into a /config/business_profile object in the BRM database:
load_pin_business_profile pin_slm_business_profile.xml
Important:
The load_pin_business_profile utility needs a configuration (pin.conf) file in the directory from which you run the utility. If you do not run the utility from the directory in which the XML file is located, include the complete path to the file. For example:
load_pin_business_profile BRM_Home/sys/data/config/pin_slm_ business_profile.xml
See "load_pin_business_profile" for more information. The PIN_FLD_NAME field in the /config/business_profile object containing the SLM business profile is set to SLM.
8.
Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
9.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide. See "Associating Bill Units with the SLM Business Profile".
10. (Optional) Make the SLM business profile your systems default business profile.
Make the SLM business profile your system's default business profile. In this case, when an account is created, its bill unit is automatically associated with the default business profile. See "Making the SLM Business Profile Your System's Default Business Profile" for more information. If the SLM business profile is not the system's default business profile, you can associate the SLM business profile with the bill unit after the account is created. See "Overriding the Default Business Profile" in BRM System Administrator's Guide for more information.
Making the SLM Business Profile Your System's Default Business Profile
To make the SLM business profile your systems default business profile:
1.
Open the bus_params_billing.xml file in an XML editor or a text editor. By default, the file is in the BRM_Home/sys/data/config directory.
2.
3.
Change string to SLM (the name of the business profile configured in (pin_slm_ business_profile.xml):
<DefaultBusinessProfile>SLM</DefaultBusinessProfile>
Caution: BRM uses the XML in this file to overwrite the existing billing instance of the /config/business_params object. If you delete or modify any other parameters in the file, the changes affect the associated aspects of BRMs billing configuration.
4. 5.
Save and close the file. If the name of your service life cycle business profile is not SLM, do the following:
a.
Open the bus_params_billing.xsl file in an XML editor or a text editor. By default, the file is in the BRM_Home/xsd directory.
b.
Validating AAA Requests for Services that Use Custom Life Cycles
c.
In the following lines of that section, replace SLM with the name of your service life cycle business profile:
<xsl:when test="normalize-space(text()) = 'SLM'"> <xsl:text>SLM</xsl:text>
For example, if the profile is named XYZ, the lines should look like this:
<xsl:when test="normalize-space(text()) = 'XYZ'"> <xsl:text>XYZ</xsl:text> d. 6. 7.
Go to the BRM_Home/sys/data/config directory. Run the following command, which loads the changes into the /config/business_ params object in the BRM database:
pin_bus_params bus_params_billing.xml
You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see "pin_bus_params" in BRM Developer's Guide.
8.
Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
9.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide. is created. See discussions about the following for more information:
10. Make sure the PIN_FLD_BILLINFO array is correctly populated when the account
PCM_OP_CUST_CREATE_ACCT opcode PCM_OP_CUST_COMMIT_CUSTOMER opcode PCM_OP_CUST_CREATE_CUSTOMER opcode Creating /billinfo objects in BRM Configuring and Running Billing
See "Changing the Default Business Profile" in BRM System Administrator's Guide for more information.
Validating AAA Requests for Services that Use Custom Life Cycles
When Services Framework AAA Manager performs AAA for a service that uses a custom life cycle, it must call a helper opcode during the VALIDATE_LIFECYCLE processing stage to validate the service request against the business rules configured for the current state of the service. By default, it calls the PCM_OP_TCF_AAA_ VALIDATE_LIFECYCLE helper opcode. To enable Services Framework to do that, you must map any service that uses a custom life cycle to the appropriate AAA opcode, processing stage, and helper opcode in the AAA opcode map (/config/opcodemap/tcf object). See "Configuring Services Framework to Call Helper Opcodes" in BRM Telco Integration for information about creating AAA opcode mapping. See BRM Telco Integration for information about AAA processing stages.
Validating AAA Requests for Services that Use Custom Life Cycles
Adding VALIDATE_LIFECYCLE Entries for the Sample Prepaid Service Life Cycle
To support the sample prepaid service life cycle, the following entries must be in the AAA opcode map:
Framework_Opcode: PCM_OP_TELCO_AUTHORIZE Processing_Stage: VALIDATE_LIFECYCLE Opcode_Map: /service/telco/gsm/telephony, PCM_OP_TCF_AAA_VALIDATE_LIFECYCLE Framework_Opcode: PCM_OP_TCF_AAA_ACCOUNTING Processing_Stage: VALIDATE_LIFECYCLE Opcode_Map: /service/telco/gsm/telephony, PCM_OP_TCF_AAA_VALIDATE_LIFECYCLE Framework_Opcode: PCM_OP_TCF_AAA_STOP_ACCOUNTING Processing_Stage: VALIDATE_LIFECYCLE Opcode_Map: /service/telco/gsm/telephony, PCM_OP_TCF_AAA_VALIDATE_LIFECYCLE
If those entries are not in the AAA opcode map, you must add them to it.
Note:
To check the entries in the AAA opcode map, display the /config/opcodemap/tcf object by using Object Browser or the testnap utility's robj command. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
To add VALIDATE_LIFECYCLE entries for the sample prepaid service life cycle to the AAA opcode map:
1. 2.
Open the BRM_Home/sys/data/config/pin_config_opcodemap_tcf file in a text editor. Add the entries to the file.
Note: If the entries are in the file but not in the AAA opcode map, the object was not loaded into the database after the entries were added to it.
3. 4.
Save and close the file. Run the following command, which loads the changes into the /config/opcodemap/tcf object in the BRM database:
Note:
To replace the entire contents of the object, use the -f parameter. To append data to the object, use the -i option.
Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide. Read the updated object with the testnap utility's robj command or with Object Browser to verify that all fields are correct.
For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
To configure Customer Center to display the names of custom service life cycle states:
1.
If your system does not have a CustomizedResources.properties file in the CC_ Home/lib directory, do the following:
a.
Copy the CCSDK_ Home/CustomerCareSDK/CustCntr/custom/CustomizedResources.properties file (where CCSDK_Home is the directory in which you installed the Customer Care SDK). Paste the copy into the CC_Home/lib directory.
b. 2.
Where
state_ID is an integer that identifies a state in a custom service life cycle (for example, 101). See "STATE_ID". state_name is a character string used as the name of the state (for example, Preactive). See "STATE_NAME".
The entry must include a state_ID#state_name element for every custom life cycle state in your system, including the states in the sample prepaid service life cycle. If you want to customize the default prepaid service life cycle names, you can do so in this entry.
Important: By default, the CustomerCenterResources.properties file has a service.state.format entry that contains the names of the states in the sample prepaid service life cycle. The service.state.format entry in the CustomizedResources.properties file, however, overrides the entry in the CustomerCenterResources.properties file. Therefore, if you add the service.state.format entry to the CustomizedResources.properties file, make sure it includes the prepaid life cycle states.
For example, suppose that you want to add two states (Telephony1 ID 109 and Telephony2 ID 110) to the prepaid service life cycle and that you created another life cycle for SMS services that has three states (SMS1 ID 111, SMS2 ID 112, SMS3 ID 113). In that case, you would add the following entry:
service.state.format={0,choice,0#No change|101#Preactive|102#Active|103#Recharge Only|104#Credit Expired|105#Dormant|106#Fraud Investigated|107#Suspended|108#Closed|109#Telephony1|110#Telephony2|111#SMS1|11 2#SMS2|113#SMS3} 3. 4.
Preactive: This is the start state of the sample prepaid service life cycle. This state indicates that the subscriber has never used the service. Typically, the service is provisioned in this state. Active: A service automatically changes to this state when the subscriber first uses the service by making a call or sending an SMS. In this state, the service start date is set, and the subscriber can perform normal service activity. The length of time a service is active depends on its balance, usage, and plan type. If the balance reaches its credit limit or if the Active state expires, the service state automatically changes to Recharge Only.
Recharge Only: An active service automatically changes to this state when its balance reaches its credit limit. In this state, the subscriber can receive calls and use free aspects of the service but cannot make prepaid calls. The subscriber can use top-ups to replenish the balance. If the subscriber does not replenish the balance before the state expires, the state changes to Credit Expired. Credit Expired: A service automatically changes to this state when its Recharge Only state expires. In this state, the subscriber cannot make or receive calls. If this state expires, the state changes to Suspended. Dormant: This state enables service providers to identify unused subscriptions and to offer subscribers incentives to resume using their services. A CSR must set this state manually through Customer Center. A dormant service has the same available features as an active service. If a subscriber uses a dormant service, its state automatically changes to Active. Fraud Investigated: This state indicates that the service's account is being examined for evidence of fraudulent activity. A CSR must set this state manually through Customer Center. In this state, the subscriber cannot make or receive calls. This state can be changed to Active or Closed. Suspended: This state implies that the subscriber intends to resume the service. In this state, no aspect of the service can be used. A subscriber might ask a CSR to suspend a service while she is on vacation or if she loses her mobile prepaid handset. Closed: This is the final state of the sample prepaid service life cycle. In this state, no aspect of the service can be used.
For an overview of state-change triggers, see "About Triggering State Changes in Custom Service Life Cycles".
REQ_ALLOWED: Specifies whether a data usage request is allowed. This rule is evaluated by the PCM_OP_TCF_AAA_VALIDATE_LIFECYCLE opcode. If it is set to Yes, the other two sample business rules are evaluated before BRM determines whether to authorize or reject the request. If it is set to No or not set, the other two sample business rules are ignored and the request is rejected. MO_ENABLED: Specifies whether mobile-originated calls are allowed. Values are Yes and No. This rule is evaluated by the PCM_OP_TCF_AAA_POL_VALIDATE_ LIFECYCLE policy opcode, which can also apply custom rules that you configure. MT_ENABLED: Specifies whether mobile-terminated calls are allowed. Values are Yes and No. This rule is evaluated by the PCM_OP_TCF_AAA_POL_VALIDATE_ LIFECYCLE policy opcode, which can also apply custom rules that you configure.
When these rules are loaded into a /config/lifecycle_states object, they are combined into one rule called CALL_ALLOWED, whose values represent various combinations of the values of all three of the preceding rules (see Table 135).
Table 135
CALL_ALLOWED Values for the Sample Prepaid Service Life Cycle MT_ENABLED No No No No Yes Yes Yes Yes MO_ENABLED No No Yes Yes No No Yes Yes REQ_ALLOWED No Yes No Yes No Yes No Yes
CALL_ALLOWED Value 0 1 2 3 4 5 6 7
For an overview of business rules and information about creating custom business rules, see "About Configuring Business Rules for Custom Service Life Cycles".
<LIFECYCLE_STATE> 101 (Preactive) 102 (Active) 103 (Recharge Only) 104 (Credit Expired) 105 (Dormant) 106 (Fraud Investigated) 107 (Suspended) 108 (Closed)
See "About Mapping States to Statuses" for more information about service state-to-status mapping.
14
14
Keep separate balances for the subscription. Create a separate bill for the subscription. Offer subscription-level discounts. Specify subscription-level credit limits.
Subscription service management can be applied to various types of customers; for example:
A single customer owns one wireless handset. A family in which one account owns multiple handsets. A corporate customer in which a sponsored account and subscription is set up for each employee.
You use Pricing Center to configure your subscription groups and Customer Center to purchase the subscription services and member services.
A subscription service represents a customers subscription, such as a wireless phone line, and includes member services. You can associate the subscription service with the customers device, such as the SIM card in a wireless handset. Member services are related to the subscription service. To purchase member services in Customer Center, you must also purchase its subscription service. You assign the devices associated with the subscription service to the member services when registering customers. For more information, see "Associating a Device with a Subscription Service".
For example, a subscription might consist of the following services as shown in Figure 141:
Figure 141 Services for a Subscription (Example)
For example, a customer owns two wireless handsets, each with a unique phone number. You set up two subscription groups in the customers account, one for each phone line as shown in Figure 142:
Figure 142 Multiple Subscriptions for an Account
You cannot transfer a subscription service that uses the accounts balance group to another subscribers account. If you want to be able to transfer the subscription service, define service-level balance groups or define a balance group for the subscription service and associate all the member services with that balance group. See "About Transferring a Subscription Service to Another Subscriber".
Typically, you also create a balance group for each member service. This makes it possible to set up shared discounts, set credit limits on service resources, and limit resource consumption to the specified service. When services have their own balance groups, cycle and usage fees for each service are tracked in the services balance group as shown in Figure 143:
You can associate all services with the subscription services balance group. When customers use member services, the cycle and usage fees are stored in the subscription services balance group as shown in Figure 144:
Figure 144 Storage of Cycle and Usage Fee
A member service can also be associated with another member services balance group to track usage for those services together. However, member services cannot use the balance group of a service that is not in the same subscription group.
When you create a balance group for a member service, any non-currency resources included with that service can be consumed by only that service. In the following figure, the data service includes 30 free minutes that can be applied only to the data service. The data service has access only to its own resources; it cannot use the free minutes included with any other service as shown in Figure 146:
Figure 146 Non-currency services with Multiple Balance Groups
You might want some types of non-currency resources to be tracked at the subscription level; for example, the number of months users have been subscribers regardless of whether theyve changed the services on their lines. To track these non-currency resources at the subscription level, you configure a counting sub-balance for the subscription service. For more information, see "About Tracking Resources in Account Sub-Balances" in BRM Setting Up Pricing and Rating.
How Products and Discounts are Selected for Rating Subscription Service Usage
Products and discounts can be owned by the subscription service, a member service, or both:
When the subscription service owns products and discounts, those products and discounts are used to rate member service usage. When the subscription service and member service both own a product, the product used for rating (the members or the subscription services) is determined by the products priority. When the subscription service and member service both own discounts, the order in which the discounts are distributed is determined by the discounts priority.
If a member service owns a discount but does not have its own balance group, its discount adjustment is applied to the subscription services balance group. You specify product and discount priority when you create products and discounts in Pricing Center. For more information, see BRM Pricing Center Online Help.
Cycle discounts, such as a 10% discount for certain months. Billing-time discounts, such as 10% off when the total usage fee exceeds $100. System discounts, such as 15% off on certain holidays for all customers. Shared discounts, such as free minutes that are distributed to services based on the services usage amount.
For more information about discounts, see "About Implementing Discounts" in BRM Configuring Pipeline Rating and Discounting. There are two ways that discounts owned by a subscription service can be distributed to member services in a subscription group:
Through inheritance: When a member service shares the subscription services balance group, any discount purchased by the subscription service is automatically inherited by the member service. The discount balance impact is applied to the subscription services shared balance group. Through a discount sharing group: When the subscription service and a member service have separate balance groups, the subscription service can share its discounts with the member service through a discount sharing group. The discount balance impact can be applied to a balance in the subscription services balance group or in the member services balance group. For more information, see "About Sharing Discounts and Sponsoring Charges for Subscription Services".
Note:
When a billing-time discount is inherited, its applied to the subscription service and every member service that inherits it. If the discount grants a percentage off of currency charges based on the total usage of all services in the group, the total discount granted can be greater than intended. If you do not want billing-time discounts to be inherited, purchase them at the member service level instead of the subscription service level. You can also configure BRM to disallow inheritance for billing-time discounts. For more information, see "Specifying Whether Billing-Time Discounts are Inherited by Member Services in Subscription Groups" in BRM Configuring Pipeline Rating and Discounting.
Discount and charge sharing groups are groups of services that share resources. These resource sharing groups consist of group owners and group members. An owner can be any one of the following, and the members can include any combination of these:
An account A subscription service A subscriptions member service A service outside the subscriptions group in the same or another account
To create subscription-level resource sharing (for example, to distribute 300 free minutes to all services on a phone line), make the subscription service the owner of the sharing group and make the member services the members of the sharing group. The service type of the subscription service must match the type of service to which the shared discount applies.
Important:
All services in a resource sharing group must have their own balance groups so that BRM can track the resources that they use and share.
For more information about discount and charge sharing groups, see "About Resource Sharing Groups" in BRM Configuring Pipeline Rating and Discounting.
A member service that is not itself a resource sharing group member (that is, it does not have its own ordered balance group), uses the ordered balance group of the subscription service. By default, the member service inherits member status in the resource sharing group from the subscription service, and the member service has access to the sharing groups resources as illustrated in Figure 147:
A member service that has its own ordered balance group does not use the subscription services ordered balance group. This is true even when the member service and subscription service belong to the same resource sharing group as illustrated in Figure 148:
Managing Customers Subscription-Level Services 14-7
If a member service and the subscription service belong to different resource sharing groups, the services have access only to the shared resources in the sharing group to which they belong as illustrated in Figure 149:
Figure 149 Restrictions for Services Using Different Resource Sharing groups
When the subscription service and a member service are both discount sharing group owners and have members in common, the sequence of the ordered balance group list for each discount sharing group member determines whether the member services discounts or the subscription services discounts are applied first. If a service is a member of both a discount and charge sharing group, the discounts are used before charges are applied. You set up discounts in Pricing Center. You define how charges are shared in Pricing Center. To create discount and charge sharing groups, you implement BRM opcodes in your customer relationship management (CRM) system.
When you inactivate a subscription service, all of its member services are inactivated. When you close a subscription service, all of its member services are closed. When you reactivate a subscription service that has been inactivated or closed, all of its member services are reactivated.
Changing the status of a member service affects only that service. If you close a member service and then close the subscription service, reactivating the subscription service does not reactivate the previously closed member service. Closing a service cancels all products and discounts owned by that service. If you reactivate a service and want to restore canceled products and discounts, you must repurchase those products and discounts for the service.
About Setting Up a Subscription Service About Configuring a Subscription Service Group About Adding Deals to Subscription Services About Setting Up Balance Groups for Subscription Services About Setting Up Subscription-Level ERAs About Modifying Subscription Services
To create custom storable objects that represent subscription services, see "Creating Custom Fields and Storable Classes" in BRM Developer's Guide.
You can configure a subscription service group by using only the services included in the plan. You can create subscription services in two ways:
When creating a plan in Pricing Center. When customers purchase the plan, the member service objects are created and associated with the subscription service object. Additional member services can be added during customer registration. To create subscription services by using Pricing Center, see Creating a Subscription Group. Subscription groups are configured in Pricing Center; the deals associated with the subscription and member services can be purchased in Customer Center.
If you implement your own customer relationship management (CRM) system, customer service representatives (CSRs) can dynamically set up subscription services or add member services to an existing subscription service when registering customers. To create subscription service groups when registering customers, you implement BRM opcodes in your CRM system.
When setting up subscription services during customer registration, you specify which balance group each service in the group should use. You can change the credit limit on a balance group for a subscription service in Customer Center.
Add a member service to a subscription group. Add deals to a service in a subscription group. Change the status of a service in a subscription group.
To modify a subscriptions services when setting up services in Pricing Center, see the Online Help. To modify the subscription and member services that a customer has purchased in Customer Center, see "Managing Services". Otherwise, to modify a subscriptions services after customers have purchased them, you implement BRM opcodes in your CRM system.
The account that owns the subscription service is closed. The subscription service has expired. The subscription service is canceled by a CSR; for example, in Customer Center.
Closes the subscription service and all of its member services. See "About Service Status when a Subscription Service is Canceled". Cancels the products and discounts associated with the subscription service and its member services. See "Effect of Canceling a Subscription Service on Products and Discounts Owned by the Service". Deletes the sharing groups owned by the subscription service and its member services, and removes the services from any sharing groups of which they are
14-11
members. See "Effect of Canceling a Subscription Service on Resource Sharing Groups Owned by the Service".
Bills the account, if specified. See "About Billing upon Subscription Service Cancellation".
Your CSRs can use Customer Center to cancel subscription services as they cancel other services. To cancel subscription services with your client application, you implement BRM opcodes. For more information, see "Canceling a Subscription Service".
The status-flag value of the subscription service is set to PIN_STATUS_FLAG_ CANCEL_LINE, and the status-flag value of the member services are set to PIN_ STATUS_FLAG_DUE_TO_SUBSCRIPTION_SERVICE, which specifies that the member services status was changed due to the status change of the subscription service. The purchase, usage, and cycle end dates for the subscription service and all of its member services are set to the cancellation date.
For more information, see "How Service Status Changes Affect Subscription Services".
Effect of Canceling a Subscription Service on Products and Discounts Owned by the Service
Canceling a subscription service cancels all the product and discount instances owned by the service and its member services.
The status of the product and discount instances owned by the subscription service and its member services are set to canceled. The purchase, usage, and cycle end dates for the canceled product and discount instances are set to the subscription service cancellation date.
Effect of Canceling a Subscription Service on Resource Sharing Groups Owned by the Service
A subscription service and its member services can own a resource sharing group, be members of a resource sharing group, or both. When a subscription service is canceled, BRM does the following:
For each sharing group member, it deletes the sharing groups balance group from the group members ordered balance group list. Removes the subscription service and its member services from any sharing groups in which they are members.
For more information about sharing groups, see "About Resource Sharing Groups" in BRM Managing Accounts Receivable.
Transferring a subscription service also transfers all member services to the new subscribers account. The member service objects are updated to reference the new subscribers account object. You can transfer a subscription service from a closed account to an account that is active, as well as transfer a subscription service from an active account to an account that is closed. When a subscription service is transferred from a closed account to an active account, the subscription service's status remains closed after the transfer. You must manually activate the subscription service. When a subscription service is transferred from an active account to a closed account, the subscription service's status remains active after the transfer. In this case, you must manually activate the closed account. If you want to disallow the transfer of a subscription service to an account that is closed, you can do this by using event notification and writing a custom opcode to generate an error when the subscription service transfer event occurs. For more information about using event notification, see "Using Event Notification" in BRM Developer's Guide.
Important:
When you transfer a subscription service from one account to another, its balance group is also transferred. If the subscription service (or one of its member services) uses an account-level balance group, however, that balance group cannot be transferred. (Transferring the account-level balance group would leave the original account without a balance group, which is not allowed.) As a result, the subscription service itself cannot be transferred. To avoid this problem, the subscription service and member services should use service-level balance groups. You can define a balance group for the subscription service and associate all the member services with that balance group. See "About Creating and Managing Subscription Services". To transfer a subscription service from one subscribers account to another, both accounts must exist in the same database. To transfer a subscription service between accounts stored in multiple databases, you must first migrate the accounts to the same database and then perform the service transfer.
Accounts A and B are stored in Database 1 Accounts X and Y are stored in Database 2
To transfer a subscription service from Account X to Account A, you must move Account X to Database 1, then transfer the subscription service to Account A. If after moving Account X to Database 1, you want to transfer a subscription service from Account Y to Account X, you must move Account Y to Database 1, then transfer the subscription service to Account X. BRM provides the Account Migration Manager (AMM), which can be used to migrate accounts between databases.
14-13
Important:
AMM is an optional feature. Contact your BRM account manager for information about using AMM.
The following functions are not supported for subscription service transfer: Transferring a subscription service across different brands. Backdating of a subscription service transfer.
Each time a subscription service is transferred, BRM stores information about the old account and the date and time when the transfer occurred in a transfer list. The transfer list is stored in the /service object. Information stored in the transfer list is used by BRM to rate and record any delayed events and call details records (CDRs) and to bill for usage created prior to the service transfer for the old subscribers account. To transfer subscription services, you implement BRM opcodes in your client application. For more information, see "Transferring a Subscription Service".
Service profiles. See "About transferring service profiles associated with a subscription service". Devices and associated phone numbers for the service. See "About transferring devices associated with a subscription service". Products and discounts. See "About transferring products and discounts associated with a subscription service". Service resource sub-balances and billing information. See "About Transferring Service-Level Balance Groups during Subscription Service Transfer". Service groups. See "How a subscription service transfer affects charge and discount sharing groups owned by the service".
About transferring service profiles associated with a subscription service In BRM, you can create service profiles to store additional information about the service. A service profile object is associated with a service and the account that the service belongs to. When a subscription service is transferred to a new subscribers account, the profile objects associated with the subscription service and the member services are updated to reference the new subscribers account object. For more information about profiles, see "About Collecting Nonstandard Account Information". About transferring devices associated with a subscription service In BRM, devices such as a mobile phone are associated with services. A device object is associated with a service and the account that the service belongs to. When a subscription service is transferred to a new subscribers account, the devices associated with the subscription service and the member services are updated to reference the new subscribers account object.
For more information about devices, see "Managing Devices With BRM" in BRM Developer's Guide. About transferring products and discounts associated with a subscription service BRM rates events by using the product and discount information associated with the service for which the events are generated. The purchase, cycle, and usage start and end dates define the validity periods during which a product or a discount can be purchased and cycle fees and usage charges can be applied. When a subscription service is transferred, BRM cancels the products and discounts associated with the subscription service and member services for the old subscriber account by setting the end dates to the transfer date. When delayed billing is enabled, delayed events and CDRs are rated and discounted by using the canceled products and discounts for the old subscribers account. For delayed events to be rated and discounted for the old subscribers account, the canceled product and discount instances must persist in the account. For more information, see "Rating Delayed Events for Canceled Products" and "Rating Delayed Events for a Canceled Discount".
Important:
Another instance of the products and discounts associated with the subscription service and member services is added to the new subscribers account with the purchase, cycle, and usage start dates set to the transfer date. The end dates are set to the old end dates. Events generated by the subscription service after the transfer date are then rated and discounted for the new subscribers account.
Note:
To discount any charges associated with the products, such as the prorated cycle fee amount, the discount instances are added to the new subscribers account before the product instance. When a subscription service is transferred, the subscriber accounts are not charged with any purchase or cancellation fees that are generally applied when a product or discount is purchased or canceled. When a subscription service is transferred, customized products are transferred along with their base product.
For more information about customers products and discounts, see "Managing Customers Services and Products". About transferring sponsored products When a subscribers account owns sponsored products, the sponsored products are associated with the sponsor group that the subscriber is a member of. The balance impacts for the sponsored products are applied to the sponsor group owner account. When a subscription service is transferred, one of the following occurs for sponsored products:
If the new subscriber account is not a member of any sponsor group, reference to the sponsor group is removed from the product instance.
14-15
If the new subscriber account is a member of another sponsor group and the same product is sponsored, reference to the sponsor group is changed to the new sponsor group in the product instance. If the product was not sponsored for the old subscriber account but is sponsored for the new subscriber account, a reference to the new sponsor group is added to the product instance.
For more information about sponsorship, see "About Resource Sharing Groups" in BRM Managing Accounts Receivable. How a subscription service transfer affects charge and discount sharing groups owned by the service Charge sharing and discount sharing groups associated with the subscription service or member services are not transferred when the subscription service is transferred to a new subscribers account. When a subscription service or member service owns a discount sharing or charge sharing group, the group is deleted when the service is transferred, and the groups balance group is deleted from the ordered balance group list for each member in the group. You need to re-create the groups for the service after the service has been transferred into the new subscribers account. When a subscription service or member service is a member of a charge sharing or discount sharing group, the service is deleted from the group when it is transferred, and the groups balance group is deleted from the ordered balance group list for the service. The service must be added back to the group after the service has been transferred. For more information about deleting a sharing group or deleting a sharing group member, see "About Sponsor Groups" in BRM Developer's Guide.
Note:
You cannot transfer subscription services that use account-level balance groups. When you transfer a subscription service from one account to another, its balance group is also transferred. If the subscription service (or one of its member services) uses the account-level balance group, however, that balance group cannot be transferred. (Transferring the account-level balance group would leave the original account without a balance group, which is not allowed.) As a result, the subscription service itself cannot be transferred. To avoid this problem, subscription services should use service-level balance groups. See "About Creating and Managing Subscription Services". BRM does not allow movement of a balance group from one bill unit to another when the balance groups bill unit has unallocated payments or adjustments, open refunds, or unresolved disputes. However, this restriction does not apply when a balance group is moved to another account as a result of a subscription service transfer.
How events are assigned to bill items after a subscription service transfer Each billable event generated by a subscription service is assigned to a bill item (/item). During billing, charges from all the bill items are collected in a bill for the subscribers account. When a subscription service is transferred, BRM creates new bill items for the new subscribers account by using item configurations (/config/items). Events generated after the transfer date are assigned to the new bill items. The new bill items are tied to the bill unit (/billinfo) that is referenced by the services balance group in the new subscribers account. As a result, charges for the new events are applied to the new subscribers account. Delayed events and CDRs are assigned to the bill items in the old subscribers account. The bill items are associated with the old subscribers bill unit; therefore, charges for the bill items are applied to the old subscribers account.
Original sub-balance: By default, resources in this sub-balance are valid from the start of the original accounts current billing cycle to the transfer date. New sub-balance: By default, resources in this sub-balance are valid from the transfer date to the end of the new accounts current billing cycle.
Before a subscription service is transferred, a resource is stored in a single sub-balance. After a subscription service is transferred, each resource is prorated and stored in two sub-balances, the original sub-balance and a new sub-balance.
14-17
Note:
To create separate sub-balances with different validity periods, the balance impact that grants the free resource must have a non-zero relative cycle start date. If the balance impacts relative cycle offset in the cycle forward or cycle arrears rate plan is set to 0, a new sub-balance is not created. Instead, the resources are added to the original sub-balance and are valid forever.
Rating and discounting impact the resources in the original sub-balance for delayed events generated by the service prior to the transfer date. Resources in the new sub-balance are consumed for new events generated by the subscription service after the transfer date. By default, the original sub-balance always expires on the transfer date. Because events generated by the new account occur after the transfer date, the new account cannot consume free resources from the original sub-balance. You can extend the validity period of the original sub-balance so that its free resources can be consumed by the new account. See "About Extending Sub-Balance Validity when a Subscription Service is Transferred".
Cut: This is the default. This option sets the validity period from the start of the original accounts current billing cycle to the service transfer date. Maintain: This option retains the original end date of the bucket. This is true even in the case of a product cancellation or line transfer.
Align: This option sets the validity period from the start of the original accounts current billing cycle to the end of the new accounts current billing cycle.
Note:
Setting the sub_bal_validity business configuration parameter extends the validity period of the original sub-balance only. The resources in the new sub-balance are always valid from the service transfer date to the end of the new accounts billing cycle. Extending the validity period of the original sub-balance extends only the time the free resources in the bucket are accessible and does not change the resource proration. The free resources are prorated based on the service transfer date. For more information, see "How Cycle Fees are Prorated when a Subscription Service is Transferred". If you do not configure the sub_bal_validity parameter, BRM sets the original sub-balance to expire on the service transfer date, and the new account cannot access this sub-balance.
To configure sub-balance validity, see "Configuring Sub-Balance Validity for Subscription Service Transfer".
14-18 BRM Managing Customers
Example 1 When sub_bal_validity is set to Cut, the rollover and original sub-balance buckets valid_to dates are set to the transfer date. The resources in the original sub-balance are prorated and a new sub-balance is created with 100 free minutes. A delayed CDR for Account A is recorded on January 17 for 200 minutes. When the CDR is rated, 50 minutes are consumed from the rollover sub-balance and 100 minutes are consumed from the original sub-balance. The balance in these two sub-balances becomes 0. Because the CDR occurred before January 15, it cannot consume minutes from the new sub-balances, and Account A is charged for the remaining 50 minutes of usage. Figure 1411 illustrates this example.
14-19
Example 2 When sub_bal_validity is set to Maintain, the rollover and original sub-balance buckets valid_to dates are extended to the end of Account As billing cycle. A delayed CDR for Account A is recorded on January 17 (after the service transfer date) for 200 minutes. When the CDR is rated, 50 minutes are consumed from the rollover sub-balance and 100 minutes are consumed from the original sub-balance. The balance in these two sub-balances becomes 0. Because the CDR occurred before January 15, it cannot consume minutes from the new sub-balance, and Account A is charged for the remaining 50 minutes of usage. Figure 1412 illustrates this example.
Figure 1412 Example 2
Example 3 When sub_bal_validity is set to Align, the rollover and original sub-balance buckets valid_to dates are extended to the end of Account Bs billing cycle. A CDR for Account B is recorded on February 3 for 200 minutes. Because the validity period of the rollover and original sub-balance is extended until February 10, 50 minutes are consumed from the rollover sub-balance and 100 minutes are consumed from the original sub-balance. The remaining 50 minutes are consumed from the new sub-balance. The balance in the rollover and original sub-balance buckets becomes 0,
14-20 BRM Managing Customers
and the balance in the new sub-balance becomes 50. Figure 1413 illustrates this example.
Figure 1413 Example 3
How Non-Currency Resources are Rolled Over when a Subscription Service is Transferred
You can configure rollover so that non-currency resources associated with cycle forward fees are rolled over for use in future cycles. For more information, see "About Rollovers" in BRM Setting Up Pricing and Rating. When a subscription service is transferred, the free resources in the rollover and original sub-balance buckets are rolled over when sub_bal_validity is set to Maintain or Align.
Note:
The rollover and original sub-balance buckets are not rolled over when sub_bal_validity is set to Cut.
The following example demonstrates how unused resources are rolled over when a subscription service is transferred to another account. In this example:
The subscription service grants 200 free minutes valid from January 1. The subscription service is transferred to the new subscribers account on January 15. The billing cycle for the original account starts on the first of each month. The billing cycle for the new account starts on the 15th of each month. The sub_bal_validity business configuration parameter is set to Maintain. Rollover minutes from the previous cycle are 50.
A maximum of 50 free minutes can be rolled over to the next cycle. The maximum number of rollover cycles is 1.
14-21
The maximum number of free minutes that can be rolled over from previous months is 100.
On January 1, the old subscribers account is granted 200 free minutes for the month of January. On January 15, the subscription service is transferred to the new subscribers account. The 200 minutes are prorated and put in two buckets with different validity dates: the original bucket (Sub-balance 1) and a new bucket (Sub-balance 2). Figure 1414 illustrates this example.
Figure 1414 Example 4a
When pin_bill_day is run on February 1, 50 minutes from Sub-balance 1 are rolled over. Because Sub-balance 1 is valid for a partial cycle (from January 15 to February 1 instead of January 15 to February 15), the resources are rolled over for one entire cycle. As a result, the Rollover 2 bucket is valid until March 15, which is the next accounting cycle end date for Account B. When pin_bill_day is run on February 15, 50 minutes from Sub-balance 2 are rolled over into a new bucket (Rollover 3) and are valid until March 15. The new account is granted an additional 200 minutes for the new cycle (Sub-balance 3). Figure 1415 illustrates the billing timeline associated with this example.
Figure 1415 Example 4b
Because the Rollover 2 and Rollover 3 buckets are valid after the transfer date, only the new account can access the resources in these buckets. The old account cannot consume the free minutes from these buckets.
How Billing Time Discounts and Folds are Applied when a Subscription Service is Transferred
Billing time discounts and folds are applied at the end of the accounting cycle and are based on resources used during the cycle. In BRM, resource balances are stored and tracked in account-level or service-level balance groups. When a subscription service is moved to a new subscribers account, the service-level balance group is transferred to the new subscribers account. As a result, billing-time folds and discounts are applied to the new subscribers account. See "About Transferring Service-Level Balance Groups during Subscription Service Transfer". For more information about billing time discounts, see "About Implementing Discounts" in BRM Configuring Pipeline Rating and Discounting.
14-23
Important:
To achieve correct rating results when rating delayed events, you must rerate the events for both the original and new account in the correct sequence. For more information about rerating, see "About Rerating Events" in BRM Setting Up Pricing and Rating.
To transfer a subscription service from Account A to Account B, both accounts must reside in the same database. You must move Account B to Database A or Account A to Database B, and then transfer the service to Account B. If, after the service transfer, you want to migrate Account A or Account B to Database C, the AMM does not allow the migration because rerating requires the original account and the account to which the service was transferred to reside in the same database. If you want to transfer the service again to Account C, you must move Account C to Database A, then transfer the service.
sub_bal_validity is a system-wide parameter. By default, this parameter is set to Cut. Changing the value of this parameter affects the sub-balance validity period for any subscription service transfer that occurs after the change. For more information, see "About Extending Sub-Balance Validity when a Subscription Service is Transferred".
Caution!:
If you change the sub_bal_validity parameter (for example, from Align to Maintain), BRM does not keep a record of the original setting. BRM uses the new setting for any subscription service transfers that occur after the change.
Note:
If you do not configure the sub_bal_validity parameter, BRM follows the default implementation by setting the original sub-balance to expire on the service transfer date.
To extend the validity of the original sub-balance, you modify a field in the /config/business_params object created during BRM installation. You modify the /config/business_params object by using the pin_bus_params utility. For information on this utility, see "pin_bus_params" in BRM Developer's Guide.
1.
Use the following command to create an editable XML file from the billing instance of the /config/business_params object:
pin_bus_params -r BusParamsBilling bus_params_billing.xml
This command creates the XML file named bus_params_billing.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.
2.
3.
Maintain if you want to extend the validity of the original sub-balance to the end of the original accounts current billing cycle. Align if you want to extend the validity of the original sub-balance to the end of the new accounts current billing cycle. BRM uses the XML in this file to overwrite the existing billing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRMs billing configuration.
Caution!:
4. 5. 6.
Rename the file from bus_params_billing.xml.out to bus_params_billing.xml. Save and close the file. Use the following command to load the change into the /config/business_params object:
pin_bus_params bus_params_billing.xml
You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. BRM_Home is the directory in which you installed the BRM software. To execute it from a different directory, see "pin_bus_params" in BRM Developer's Guide.
7.
Read the object with the testnap utility or the Object Browser to verify that all fields are correct. See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.
8. 9.
Stop and restart the Connection Manager (CM). For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide. For multiple databases, run the pin_multidb script with the -R CONFIG parameter. For more information on this script, see "pin_multidb" in BRM System Administrator's Guide.
14-25
Use Pricing Center to map the subscription service in the following Pipeline Manager database tables:
IFW_SERVICE specifies the pipeline rating service code to real-time rating service code mapping; for example, map GSM to /service/telco/gsm. IFW_SERVICE_MAP specifies the external data used to determine the internal service code. You define the mapping when you set up service code mapping. IFW_REF_MAP specifies the service type to event type mapping so that the services in your price list are associated with usage events. This database table also specifies the prefix for the data that identifies an account; for example, MSISDN or IMSI. Be sure to map a corresponding delayed event type to your subscription service object. For example, if you map to the usage event type /event/session/telco/gsm, also map to /event/delayed/session/telco/gsm. The delayed event type is used by Rated Event (RE) Loader when loading the rated events into the BRM database. For more information, see "Understanding Rated Event Loader" in BRM Configuring Pipeline Rating and Discounting.
Important:
If the delayed event type does not already exist in the BRM database, you must create one. See "Adding New Event Types for RE Loader to Load" in BRM Configuring Pipeline Rating and Discounting.
IFW_ALIAS_MAP specifies which data to use for looking up an account in order to get the parameters for rating usage. You define the alias mapping when you set up EDR container fields. For more information, see "Modifying and Loading the EDR Container Description" in BRM Configuring Pipeline Rating and Discounting. To define the alias mapping by using Pricing Center:
a. b. c.
Choose EDR - EDR Container Description from the Pipeline Setup Toolbox. In the EDR Container Description dialog box, select the ALL_RATE sample container description and click Edit. Click the Alias Map tab and enter the alias data information for the subscription service.
For more information about mapping pipeline data, see "Setting up Pipeline Price List Data" in BRM Configuring Pipeline Rating and Discounting.
Important:
If a member services balance group is not associated with a bill unit, charges for that service are not billed.
You can create a bill unit for a subscription or use the accounts bill unit (the AR bill unit). If you use the accounts bill unit, charges for any service owned by the account that are not part of the subscription are also included in the bill. You use Customer Center to create bill units and associate them with balance groups. You can also create and manage bill units by using the BRM API. See "Managing Bill Units With Your Custom Application" in BRM Configuring and Running Billing.
If the Bill Now option is not specified, the service is billed during the regularly scheduled billing time.
When the Bill Now option is specified, the subscribers account is billed for all current charges generated by the subscription service until the cancellation date. Delayed events for the service recorded after the cancellation date are billed on the next regularly scheduled billing date. In the example shown in Figure 1416, the subscription service is canceled on January 17 with the Bill Now option specified. Bill B1 includes all current charges between January 1 and January 17. Bill B1 includes all delayed charges for the service recorded after the cancellation date.
14-27
When the Bill Now option is specified, BRM bills the bill units (/billinfo) associated with the subscription service. Typically, all the member services are associated with the subscription services bill unit. However, a member service can have its own bill unit. By default, any other service belonging to the same bill unit as the canceled subscription service or its member services bill unit are also billed. If you do not want other services in the bill unit to be billed immediately, do one of the following:
Wait for the regular billing day, and bill the canceled subscription service along with the other services in the bill unit. Customize the PCM_OP_BILL_POL_GET_PENDING_ITEMS policy opcode to include only the pending bill items for the subscription service that was canceled.
You can extend your customer management application to create a Bill Now for a specific service. For more information, see:
How an Account is Billed when a Subscription Service is Canceled during the Billing Delay Period
When a subscription service is canceled during the billing delay period with the Bill Now option specified, the subscribers account is billed immediately for all current charges that includes charges from the current billing cycle and the previous billing cycle. Delayed events recorded after the cancellation date are billed on the regularly scheduled billing date. In the example shown in Figure 1417, the subscription service is canceled during the billing delay period on February 5. Bill B1 includes all current charges from January 1 to February 5 for both billing cycle B1 and billing cycle B2. Delayed events for billing cycle B1 recorded after February 5 are billed on February 10. Events generated for billing cycle B2 after February 5 are billed on March 10.
Figure 1417
Example 6
In each service array, set the PIN_FLD_SUBSCRIPTION_INDEX field to specify the index of the array that contains the subscription service.
14-29
Note:
When you add standalone services to a price plan, you set the PIN_FLD_SUBSCRIPTION_INDEX field to 0. This value indicates that the service is not a member of a subscription group.
Add a PIN_FLD_BAL_INFO array to create a balance group for the subscription service. Optionally, specify any subscription-level credit limits or thresholds. Add an additional PIN_FLD_BAL_INFO array for each member service that should have its own balance group, and set credit limits and thresholds, if any. A member service that does not have a balance group uses the subscription services 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.
The PIN_FLD_SUBSCRIPTION_INDEX field specifies an existing element ID of the PIN_FLD_SERVICES array. If the element ID does not exist, the PIN_PRICE_ ERR_INVALID_SUBSCRIPTION_INDEX error is returned. Member services from different subscription groups do not share the same balance group. If the PIN_FLD_BAL_INFO_INDEX field for two services that belong to different subscription groups specify the same balance group index array element, the PIN_PRICE_ERR_INVALID_BAL_INFO_INDEX error is returned.
The following example shows an flist with the fields that pertain to subscription service groups. The plan includes three services in a subscription group, one subscription service, and two member services. All services use the subscription services balance group:
. . . 0 PIN_FLD_BAL_INFO ARRAY [1] allocated 2, used 2 //the subscription services balance group 1 PIN_FLD_NAME STRING [0] subscription 1 PIN_FLD_LIMIT ARRAY [840] allocated 3, used 3 2 PIN_FLD_CREDIT_FLOOR DECIMAL [0] 0.0 2 PIN_FLD_CREDIT_LIMIT DECIMAL [0] 500.0 2 PIN_FLD_CREDIT_THRESHOLDS INT [0] 0 0 PIN_FLD_SERVICES ARRAY [1] allocated 3, used 3 // Array of the subscription service 1 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/telco/gsm -1 0 //The subscription service object. 1 PIN_FLD_SUBSCRIPTION_INDEX INT [0] 1 //The index of the subscription service. Note that it references itself. 1 PIN_FLD_BAL_INFO_INDEX INT [0] 1 //The index of the subscription services balance group array. . . . 0 PIN_FLD_SERVICES ARRAY [2] allocated 3, used 3 1 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/telco/gsm/telephony -1 0 // Member service. 1 PIN_FLD_SUBSCRIPTION_INDEX INT [0] 1 1 PIN_FLD_BAL_INFO_INDEX INT [0] 1 . . . 0 PIN_FLD_SERVICES ARRAY [3] allocated 3, used 3 1 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/telco/gsm/sms -1 0 // Member service. 2 PIN_FLD_SUBSCRIPTION_INDEX INT [0] 1 3 PIN_FLD_BAL_INFO_INDEX INT [0] 1 . . .
When registering customers, use the PCM_OP_CUST_COMMIT_CUSTOMER opcode. When customers purchase a plan for an existing account, use the PCM_OP_CUST_ MODIFY_CUSTOMER opcode.
These opcodes call other opcodes to set up a customers services and create the service objects. These opcodes set the subscription group relationship fields in the service objects that they create. Services are created in the following order: account-level services, the subscription service, and member services in the subscription group. To create a subscription service group, set the following fields in the input flist of PCM_OP_CUST_CREATE_CUSTOMER and PCM_OP_CUST_MODIFY_CUSTOMER:
In each service array, set the PIN_FLD_SUBSCRIPTION_OBJ field to specify the Portal object ID (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 any subscription-level 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 services 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.
When registering customers, use PCM_OP_CUST_COMMIT_CUSTOMER. When customers purchase a plan 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 subscription-level ERA for a specific customer, add a PIN_FLD_ PROFILES array to the subscription services 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.
14-31
To configure the ERA with customer-specific data, write custom code that sets the customers information in the PIN_FLD_DATA array of the /profile/serv_extrating object. To validate the customers profile information, you must modify the PCM_OP_CUST_ POL_VALID_PROFILE policy opcode. See the opcode documentation for more information. You can also use the Customer profile opcodes to create and modify /profile objects directly. See "Managing and Customizing Profiles".
When registering customers, use PCM_OP_CUST_COMMIT_CUSTOMER. When customers purchase a plan 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 subscription service, set the following fields in the subscription services PIN_FLD_SERVICES array on the input flist of the customer opcodes:
Specify the POID of the /device object in the PIN_FLD_DEVICE_OBJ field of the PIN_FLD_DEVICES array. Specify the number associated with the device (such as the IMSI or MSISDN) in the PIN_FLD_ALIAS_LIST array.
You can also use the PCM_OP_CUST_UPDATE_SERVICES opcode to modify /device objects. This opcode calls the PCM_OP_DEVICE_ASSOCIATE opcode to associate or disassociate a device with a service. To directly create or modify device objects, use the PCM_OP_DEVICE* opcodes.
Set PIN_FLD_POID to the POID of the account object that owns the subscription service. 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.
If the PIN_BILL_FLG_BILL_NOW flag is passed in the input flist, calls the PCM_ OP_BILL_MAKE_BILL_NOW opcode for each bill unit (/billinfo object) associated with the subscription service.
Note:
Typically, all the member services are associated with the subscription services bill unit. However, it is possible for member services to be associated with different bill units.
2.
Calls the PCM_OP_CUST_UPDATE_SERVICES opcode to update the status of the subscription service and member services. PCM_OP_CUST_UPDATE_SERVICES does the following:
a. b. c.
Updates the status of the subscription service and all of its member services to closed. Updates the status of all discounts and products associated with the subscription service and member services to canceled. Deletes any resource sharing groups owned by the subscription service and the member services, and updates the ordered balance group (/ordered_ balgrp object) of the group members. Removes the subscription service and member services from any resource sharing group of which they are members.
d. 3.
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 audit event /event/audit/subscription/cancel that was created to record the cancellation.
14-33
To transfer a subscription service to another subscribers account, use PCM_OP_ SUBSCRIPTION_TRANSFER_SUBSCRIPTION. Specify the following information in the PCM_OP_SUBSCRIPTION_TRANSFER_ SUBSCRIPTION opcode input flist:
The POID of the account object from which the service is transferred. The POID of the account object to which the service is transferred. The POID of the subscription service to transfer. The POID of a bill unit (/billinfo object) and the POID of a payinfo object (/payinfo): If the service is to be associated with an existing bill unit in the new subscribers account, specify the POIDs of any existing bill unit and payinfo objects. If the service is to be associated with a new bill unit created for the service only, specify the POIDs of the new bill unit and payinfo objects.
The POID of an existing payment object (/payinfo) for the new subscriber or the POID of a new payment object created for the service only.
To transfer the services, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following for each member service:
1. 2. 3.
Sets the account object POID to the new subscribers account object POID. Creates a transfer list array element and adds it to the service objects. Creates the audit event /event/audit/subscription/transfer to record the service transfer.
To transfer the devices, PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following for each member service:
1. 2.
Finds all the devices owned by the service and sets each devices account object POID to the new subscribers account object POID. Creates the audit event /event/audit/subscription/transfer to record the device transfer.
To transfer the products and discounts, PCM_OP_SUBSCRIPTION_TRANSFER_ SUBSCRIPTION cancels the products and discounts owned by the old subscribers account and creates copies for the new subscribers account. To do this, it does the following for each member service:
1. 2.
Finds all products and discounts associated with the service owned by the existing subscribers account. For each product instance:
a.
Calls the PCM_OP_SUBSCRIPTION_SET_PRODINFO opcode to set the purchase, cycle, and usage end dates to the transfer date for the old subscribers account and to apply cycle forward fees. Creates another instance of the product and assigns it to the new subscribers account with purchase, cycle, and usage start dates set to the transfer date.
b.
Note:
For customized products, the opcode does not separately set end dates in the old account and start dates in the new account. The start and end dates of customized products are adjusted automatically when the dates for their base products are set.
c.
If the product is sponsored, and the new subscribers account is not a member of the same sponsor group as the old subscribers account, the POID of the sponsor group account object is deleted from the product instance.
3.
Calls the PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO opcode to set the purchase, cycle, and usage end dates to the transfer date for the existing subscribers account and to apply cycle forward fees. Creates another instance of the discount and assigns it to the new subscribers account with purchase, cycle, and usage start dates set to the transfer date. Creates the /event/billing/discount/action/purchase event to record the discount instance transfer.
b. c.
To transfer the subscription service billing information, PCM_OP_SUBSCRIPTION_ TRANSFER_SUBSCRIPTION associates the service balance groups with an existing bill unit in the new subscribers account or with a new bill unit created for the service. To do this, it does the following:
1. 2. 3.
If a /billinfo object is specified in the input flist, it sets the PIN_FLD_BILLINFO_ OBJ field in the services /balance_group object to reference the /billinfo object. If a /payinfo object is specified in the input flist, it sets the PIN_FLD_PAYINFO_ OBJ field in the services /balance_group object to reference the /payinfo object. If a /billinfo object is not specified, it calls the PCM_OP_CUST_SET_BILLINFO opcode to create a new /billinfo object and sets the PIN_FLD_BILLINFO_OBJ field in the services /balance_group object to the newly created /billinfo object. If a /payinfo object is not specified, it calls the PCM_OP_CUST_SET_PAYINFO opcode to create a new /payinfo object and sets the PIN_FLD_PAYINFO_OBJ field in the services /balance_group object to the newly created /payinfo object.
4.
To transfer the subscription services resource sub-balances, PCM_OP_ SUBSCRIPTION_TRANSFER_SUBSCRIPTION does the following:
1. 2. 3.
Modifies the services /balance_group object to reference the /billinfo object in the subscribers account. Sets the sub-balance validity based on the sub_bal_validity parameter in /config/business_params. Creates the audit event /event/audit/subscription/transfer to record the balance group transfer.
When a subscription service is transferred to a new subscribers account, it is deleted from any group of which it is a member. PCM_OP_SUBSCRIPTION_TRANSFER_ SUBSCRIPTION does the following for each member service:
Managing Customers Subscription-Level Services 14-35
1. 2.
Finds the charge sharing or discount sharing groups that the service is a member of and deletes the service from the group. Deletes any ordered balance group associated with the service.
When a subscription service is transferred to a new subscribers account, any group that it owns is deleted. PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION finds the charge sharing group or discount sharing group that it owns and deletes the group for each member service.
15
15
This chapter describes how to create and use profile sharing groups in your Oracle Communications Billing and Revenue Management (BRM) system. To use this documentation, you should be familiar with extended rating attributes (ERAs). See "About Extended Rating Attributes" in BRM Configuring and Running Billing.
Only service-level profiles can be shared. Account-level profiles cannot be shared, even if the profile sharing group is owned by an account.
Profile sharing can be used to share an ERA, such as a friends and family list, to make it available to multiple accounts or services. For example, a friends and family list can be set up for a GSM service owned by one account and then shared so that a GSM service belonging to other accounts can use the same list, as shown in Figure 151:
With this feature, you do not need to set up the same friends and family list or other ERA values separately for different accounts: theyre shared automatically. Profile sharing groups can also be used to share custom profiles you create. You can set up profile sharing groups in two ways:
Using Customer Center. Using a customized third-party client application. See "Creating a Profile Sharing Group through a Customized Client Application".
For guidelines that apply to both creation methods, see "Creating Profile Sharing Groups".
Note:
Profile sharing groups work similarly to charge and discount sharing groups, but profile sharing groups do not share resources and are not prioritized.
Account: If an account is a member, any eligible event generated by the account can use a shared profile. Service type: When you specify a service type (for example, GSM) as a member, the events generated by all service instances within that service type are considered for shared profiles. You can also specify that a member account that has not yet purchased a service of that type is automatically eligible for participation in profile sharing if it buys the service in the future.
Note:
The subtypes of the service type you specify do not become members. For example, if you specify the GSM service type as a member, specific GSM service instances such as GSM fax, GSM telephony, and so forth, do not.
Service instance: When you specify a service instance (for example, a specific phone) as a member, only the events generated by that instance are eligible for the shared profiles. Specify membership using a specific service instance if you want to exclude other services of that type from profile sharing. For example, if an account includes both work phone service and personal phone service, a friends and family ERA might apply only to the personal phone.
Profile sharing group members should be equivalent to the owner. If the owner is a service, then the members should be the same service type. If the owner is an account, then the members should also be accounts. Members do not need to have the same products or discounts as the owners. But to make use of a shared profile, members need a product or discount configured to use an ERA type or ERA label in the shared profile to give special rates or discounts. By default, BRM does not validate profile sharing group members. You can customize the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS policy opcode to add validation for profile sharing groups. See "Validating Profile Sharing Group Members".
When the owner of a profile sharing group changes, the profiles shared by the previous owner are deleted from the group and the profiles shared by the new owner are added.
In Customer Center.
Working with Profile Sharing Groups 15-3
To create a profile sharing group through a third-party client application, see "Creating a Profile Sharing Group through a Customized Client Application".
The owner cannot be a member of its own group. The owner of a profile sharing group cannot also belong to a member-owned group. For example, if Account1 and Account2 both own profile sharing groups, and Account2 is a member of Account1s group, then Account1 cannot belong to Account2s group. If you add a service type as a member rather than a specific service instance, all instances of that service type become members. However, the subtypes of the service type do not become members. For example, if you specify the GSM service type as a member, all instances of GSM become members, but GSM fax, GSM telephony, and so forth do not.
Creates a /group/sharing/profiles object and assigns the group owner. 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. See "About Profile Sharing Group Membership".
3. 4.
Validates that the the group owner does not belong to a profile sharing group owned by one of the members. Calls the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS policy opcode 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 will be empty. Duplicate entries are ignored.
If successful, PCM_OP_SUBSCRIPTION_SHARING_GROUP_CREATE returns the Portal object ID (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 members ordered balance group. See "Adding a Profile Group to a Members 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.
For discount and charge sharing groups, /ordered_balgrp controls the order in which the groups resource balances are impacted by events. See "How Discounts and Charges Are Applied" in BRM Managing Accounts Receivable. For profile sharing groups and balance monitor groups, the order is not significant, so they are added to the end of the list in the PIN_FLD_ORDERED_ BALGROUPS array. The balance monitor groups are listed before the profile sharing groups.
When a profile sharing group is created or modified, the PCM_OP_SUBSCRIPTION_ POL_AUTO_SUBSCRIBE_MEMBERS policy opcode automatically adds the group to the /ordered_balgrp object of each account or service that is a member.
Add members to the group: When a member is added to the group, shared profiles become available to events generated by that member.
Add shared profiles: When profiles are added to a profile sharing group, the profiles automatically are available to group members. The added profiles must be owned by the group owner and have valid dates. Delete members from the group: When a member is deleted from the group, the group owners profiles are no longer considered in rating or discounting the former members events. Delete shared profiles: A deleted shared profile is removed from the groups profiles list and is no longer available to members. Change the owner of the profile sharing group: When the owner of a profile sharing group changes, members use the new owners shared profiles instead of the old owners shared profiles.
Note:
You cannot change the owner of a profile sharing group in Customer Center.
To modify profile sharing groups by customizing a third-party application, see the following:
Modifying a Profile Sharing Group through a Customized Client Application Deleting Members and Profiles from a Profile Sharing Group through a Customized Client Application Changing the Owner of a Profile Sharing Group through a Customized Client Application
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.
Adding Members to a Profile Sharing Group through a Customized Client Application Adding Profiles to a Profile Sharing Group through a Customized Client Application
Important:
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 members 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 members element ID is the same as an existing members ID. This opcode handles duplicate members, so including existing members in the input flist does not cause problems.
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. See "Creating Profile Sharing Groups". 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. 3.
Validates that the group owner does not belong to a profile sharing group owned by one of the members. Calls the PCM_OP_SUBSCRIPTION_POL_PREP_MEMBERS policy opcode 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". Creates an flist that includes the list of members to be added to the sharing group. Generates an /event/group/sharing/profiles/modify event to record the changes.
4. 5.
Adding a member to a profile sharing group triggers the PCM_OP_SUBSCRIPTION_ POL_AUTO_SUBSCRIBE_MEMBERS policy opcode, which adds the profile sharing group to the ordered balance group for each member. See "Adding a Profile Group to a Members Ordered Balance Group".
Adds the /profile objects in the PIN_FLD_PROFILES array to the PROFILES array of the /group/sharing/profiles object. Validates that the new group name is not a duplicate of an existing group name.
3. 4.
Creates an flist that includes the list of profiles to be added to the sharing group. Generates an /event/group/sharing/profiles/modify event to record the changes.
Deleting Members and Profiles from a Profile Sharing Group through a Customized Client Application
Caution!:
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 the PCM_OP_ SUBSCRIPTION_SHARING_GROUP_DELETE opcode. To delete a profile sharing group member, PCM_OP_SUBSCRIPTION_SHARING_ GROUP_DELETE does the following:
1.
Calls the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP opcode to delete the group/sharing/profiles object from the members /ordered_balgrp object. For more information, see "Adding a Profile Group to a Members Ordered Balance Group".
2. 3.
Deletes the member from the /group/sharing/profiles members array. 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. 2.
Deletes the /profile objects specified in the PIN_FLD_PROFILES array from the PROFILES array of the /group/sharing/profiles object. 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 through a Customized Client Application
To change the owner of an existing profile sharing group, use the PCM_OP_ SUBSCRIPTION_SHARING_GROUP_SET_PARENT opcode. You cannot change the group owner in Customer Center. 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 within the same account, the object passed in this field matches the one in the PIN_FLD_POID field.
PIN_FLD_BAL_GRP_OBJ: The balance group used to track sharing activities for the new owner. PIN_FLD_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.
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. 3. 4. 5. 6.
Deletes the current owners profiles from the /group/sharing/profiles object. Adds the list of profile instances of the new parent passed in the input flist to the group object. Sets the /group/sharing/profile objects owner to the new owner specified in the PIN_FLD_PARENT input field. Adds the new owners shared profiles to the /group/sharing/profiles object. Generates an /event/group/sharing/profiles/modify event to record the owner change.
If successful, this opcode returns the POID of the profile sharing group that was modified and the event that was generated to record the owner change. This opcode fails if the new owner that is passed is already a member of the profile sharing group.
When a profile sharing group is deleted, BRM also deletes the profile sharing group from each members ordered balance group. For more information about ordered balance groups, see "Adding a Profile Group to a Members Ordered Balance Group". You delete profile sharing groups as follows:
Using Customer Center. To delete a profile sharing group through a third-party client application, see "Deleting a Profile Sharing Group through a Customized Client Application".
To delete members or profiles from a group, see "Modifying Profile Sharing Groups".
Calls the PCM_OP_SUBSCRIPTION_ORDERED_BALGRP opcode to delete the group/sharing/profiles object from each members /ordered_balgrp object. Deletes the group/sharing/profiles object. Generates an /event/group/sharing/profiles/delete event to record the deletion.
16
16
The Email DM is not related to the Email Manager, the optional BRM component that integrates your companys email service with the BRM system. You use the Email Manager to manage your customers use of your email service. See "About Email Manager" in BRM Email Manager.
After the Email DM is running, you need to set up event notification to determine the events or times that trigger a customer email. For information about emailing invoices, see "Sending Invoices to Customers" in BRM Designing and Generating Invoices. You also run Email DM to send welcome messages to new customers. For more information, see "Sending Welcome Messages to Customers".
Edit the configuration file for dm_email. See "Configuring the Email Data Manager". Start the dm_email process:
pin_ctl start dm_email
This script starts the dm_email process. For information on how to specify the sender of automatic email messages, see "Specifying the Sender of Welcome Messages".
This default should be sufficient for most users. But you can configure BRM to use different command-line options for sendmail.
Caution!: Do not change the sendmail configuration unless you are an experienced sendmail user.
1. 2. 3. 4.
Open the Email DM configuration file (BRM_Home/sys/dm_email/pin.conf). BRM_Home is the directory in which you installed the BRM software. Edit the unix_sendmail_command entry. You can specify different options for sendmail, but you cannot substitute a different program for sendmail. Save the file. Stop and restart the Email DM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Editing the Email Data Manager Configuration File Checking Entries in the Connection Manager Configuration File
Open the Email DM configuration file (BRM_Home/sys/dm_email/pin.conf). Edit the file according to the instructions it contains. Save the file. Stop and restart the Email DM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
Open the CM configuration file (BRM_Home/sys/dm_email/pin.conf). Make sure these entries exist in the file:
3.
If you changed the file, save it, and stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
17
17
The system currency is the default currency for your entire database. It is typically the currency of the country where your BRM system is installed. Every BRM installation includes a system currency. The default system currency is US Dollars (ISO code 840). The account currency is the currency for a specific customer account. For example, a customer living in France has euro as the account currency. All payments, balance impacts, and billing adjustments use the customers account currency. To set the system currency, see "Setting the System Currency". The account currency is set by the customer or customer service representative (CSR) when the account is created. After the account is created, you cannot change the account currency for an account. See "Defining the Currency for Individual Accounts". To set the default account currency, see "Setting the Default Account Currency".
When an event is rated, the balance impact is calculated by using the system currency. The balance impact is converted to the customers account currency and added to the balance.
When currency conversion rates change, you need to update the /config/currency/conversionrates object. See "Changing Currency Conversion Rates".
If your system currency is not US Dollars, you must set the system currency during installation. After installing BRM, you cannot change the system currency unless you use an SQL query, a method that BRM does not support.
To set the system currency to a currency other than US Dollars, do not preconfigure BRM during installation. Instead, edit the $PIN_CONF_SYS_CURRENCY entry in the pin_setup.values file and run the setup script. Example of changing the system currency to the euro:
$PIN_CONF_SYS_CURRENCY = 978;
Open the Connection Manager (CM) configuration file (BRM_ Home/sys/cm/pin.conf). BRM_Home is the directory in which you installed the BRM software. Change the value of the currency entry. For example, to change from US Dollars to British Pounds, change 840 to 826:
- fm_cust_pol currency 826
2.
3. 4.
Save and close the file. Stop and restart the CM.
You cannot change an account currency after the account has been created. An account can have only one primary currency. If a customer requires two primary currencies, you need to create two accounts for that customer.
Specify the currency when you create the account. You specify the account currency during registration by choosing from a list of currencies and secondary currencies. If your account uses two currencies, and the primary currency is the euro, the list of secondary currencies is limited to the EMU currencies for countries that are still in the currency crossover period. (Countries that joined before February, 2002 can only use the euro.) To add or remove a currency resource, see "Supporting a New Currency". To change the list of secondary currencies, see "Changing Supported Secondary Account Currencies".
Display the currency in an account in either the primary or secondary currency. Some amounts are always displayed in the primary currency.
If you add a resource when Pricing Center is running, you must refresh the price list snapshot to see the new resources.
For more information, see "About Resources" in BRM Setting Up Pricing and Rating.
Allow BRM to translate all currencies to the account currency. Create products in each currency.
Managing System and Account Currencies 17-3
If you are contractually obligated to maintain consistent charges, you might need to create products in multiple currencies. For example, to charge for Internet access time, you could create products that include Internet usage rates with different currency balance impacts. There are advantages to this approach:
You do not have to update the currency conversion rates. Your customers are billed in consistent amounts that do not change with exchange rates. When customers register, they see prices in a familiar currency.
Tip: To create multiple products by using different resources, create a set of products for one currency, then use the Product Creation wizard to copy the products for each currency.
Credit card processors typically support only a small set of currencies. See the documentation for your credit card processor.
The object can store conversion rates that apply to multiple time periods. For example, you could have different rates for the period from January 1, 2009 to July 31, 2009 and the period from August 1, 2009 to October 31st, 2009. At CM startup, BRM caches the /config/currency/conversionrates object. To support accurate conversion for suspended payments, the entire object, including all conversion rates, is cached. When you recycle a suspended payment, BRM uses the conversion rate that was valid for the period when the payment was originally made. Its important therefore to configure the /config/currency/conversionrates object to include conversion rates for all time periods that might be relevant to suspended payments.
Important:
Include only conversion rates for time periods that are required to support suspended payments. If the /config/currency/conversionrates object includes a very large number of conversion rates, caching it can consume significant amounts of memory.
By default, the conversion rates for EMU currencies to euro and for euro to EMU currencies is preconfigured and loaded into the database when BRM is installed. You define the conversion rates and their time periods by adding PIN_FLD_CUR_ RATES_TIMEFRAMES arrays to the /config/currency/conversionrates object. There is a separate array for each time period. The rates themselves are defined in the PIN_ FLD_CUR_CONV_RATES array in PIN_FLD_CUR_RATES_TIMEFRAMES. The time periods are defined by PIN_FLD_START_T and PIN_FLD_END_T fields.
Tip: To verify that you changed the fields, read the object by using the testnap utility or by displaying the /config/currency/conversionrates object in the Object Browser.
Important:
When the primary account currency is an EMU currency, the secondary currency must be the euro. BRM automatically assigns the euro as the secondary account currency. When the euro is used as the primary account currency, the customer can choose an EMU currency as the secondary currency, or choose no secondary currency.
Tip: You can specify whether BRM requires a secondary currency when the euro is the primary currency. See "Changing Supported Secondary Account Currencies".
If you have customers from many countries, you should use the euro as the system currency. That way, all currency conversion is between the euro and EMU currencies, and never between two EMU currencies, because you cannot convert between account currencies. If you must use an EMU currency as the system currency, then you should make sure that customers who have an account currency different from the system currency cannot purchase products by using the system currency. To do so, use the euro as the primary currency for those accounts.
Restrict all rates to use either the euro currency or the national EMU currencies, but not both. This ensures you do not redefine the EMU to euro conversion ratio and charge two different amounts for the same service.
If a customer pays in euros for a 100 FF charge, and the euro amount converts to 99 FF, the payment is accepted. If a customer pays in euros for a 100 FF charge, and the euro amount converts to 97 FF, the payment is not accepted.
Example of amount tolerance You might set the minimum and maximum error tolerance amounts for French Francs to 3:
If a customer pays in euros for a 50 FF charge, and the euro amount converts to 49 FF, the payment is accepted. If a customer pays in euros for a 50 FF charge, and the euro amount converts to 46 FF, the payment is not accepted.
Example of percentage and amount tolerance If you set both an error tolerance percentage and a tolerance amount, the tolerance percentage overrides the tolerance amount. For example, you might set the percentage tolerance to 1% and the minimum amount tolerance to 5. The customer pays in euros
for a 1000 FF charge, and the euro amount converts to 992. The percentage tolerance is met, so the payment is accepted, even though the amount minimum has not been met.
After you set error tolerance values for your supported currencies, you must activate the error tolerance by modifying the Connection Manager (CM) configuration file. See "Rounding Errors for Overpayments and Underpayments".
Use Event Browser to display the euro and EMU currencies and their balance impacts.
Note:
If the event involved the primary currency, you see only the primary currency. If the event involved the secondary currency, you see the primary and secondary currencies.
Use Customer Center to toggle views between the euro and EMU currencies. Use Payment Tool to enter payments in the euro or EMU currencies.
Delete entries for currencies that you do not want displayed. Delete the PIN_FLD_CREATED_T field. Delete the PIN_FLD_MOD_T field. (Optional) To use the euro as the primary account currency without using a secondary currency, change the secondary currency required field to 0:
2 PIN_FLD_CUR_SECONDARY_REQ ENUM [0] 1
Tip: To set the default secondary currency, move the currency entry to the top of the list of supported currencies. If a secondary currency is required, and the secondary account currency is not supplied during registration, the default secondary currency is the first supported currency listed.
Tip: To verify that you changed the fields, read the object by using the testnap utility or by displaying the /config/currency/supportedcombinations object in the Object Browser.
Important:
Part II
Part II
Part II describes how to implement branded services. It contains the following chapters:
18
18
About Branding
This chapter provides an overview of brands and describes brand-aware functionality in a single Oracle Communications Billing and Revenue Management (BRM) system. You must have the Brand Manager component to create and use brands.
Create a brand, by using the BRM mechanism for keeping customer accounts and other data for a BSP separate from data for other brands in the same BRM system. See "Creating Brands". Control which BRM personnel can access customer accounts and other data in each brand. See "Controlling Access to Top-Level Brands". Create separate price lists for each brand. See "Creating a Price List for Brand Accounts". Create brand-specific Web pages for customers to register and modify their accounts. See "Creating a Brand-Specific Web Page".
You need the Brand Manager component to host services for BSPs. See "When to Use Account Groups Instead of Brands" if you are not certain if your company requires branding.
About Branding 18-1
Understanding Brands
Understanding Brands
A brand is implemented as a type of BRM account. You create and modify brands by using the Brand Manager component of Configuration Center.
Note:
Because brands are a type of account, you can also view and modify them in Customer Center.
When you create a brand, you include the login names of one or more brand administrators who manage that brand. Only the host administrator, a brand administrator, or a customer service representative (CSR) with access privileges for the brand can create and modify the brand-specific data. Use Access Privileges, another Configuration Center application, to give additional BRM users access to a brand. For more information, see "About Granting Access to Brands". After the host administrator creates a brand, the brand administrator creates the price lists, customer accounts, and other data that is specific to that brand.
Brand-Aware Information
Table 181 describes how branding affects certain BRM applications and features. The descriptions in the table apply only when you implement brands.
Table 181 Branded Data Behavior Branding behavior You use the Access Privileges tool to add users to an access group for a brand or account group. The access group limits who can access and manage the branded accounts. See "About the Root Access Group". Sponsorship is valid within a brand; an account in one brand cannot not sponsor an account in a different brand, including sub-brands.
Account sponsorship
Understanding Brands
Table 181 (Cont.) Branded Data Behavior Branded data Customer Center Branding behavior You create and change accounts only in the brand you select from the Brand list in Customer Center. Only brand administrators and CSRs with proper access privileges can see brand-specific information and accounts. Host administrators and brand administrators log into Configuration Center and use Brand Manager to create brands and sub-brands. See "Creating Brands". All brands must use the credit card processing service configured for the BRM system; however, you define merchant IDs for each brand. See "Setting Up Payment Methods for Brands". Only brand administrators and CSRs with proper access privileges can see brand-specific information and accounts. /device objects and the /config objects used to configure them are brand-aware. You can associate /device objects only with /service objects in the same brand. You can specify different device life cycles and service mappings for device types in different brands. See "Device management and brands" in BRM Developer's Guide for more information. The events available through Event Browser are those related to the login and password that the CSR uses to log in to Customer Center. You can review these events to see the changes a CSR makes to accounts in a brand the CSR has access to. The host administrator defines one set of G/L IDs for the database and one G/L segment for each brand in the database. You set up G/L information for brands in the pin_glid file. BRM Reports The host administrator must install and configure BRM Reports, after which brand administrators can create reports for their brand. See "Reporting by brand" in BRM Reports for more information. The host administrator can change the default invoice template for a BRM system. Brand administrators can design custom invoice templates and save them to their brands. Multidatabase support If your BRM system is installed in a multidatabase environment, you can install each top-level brand in a chosen database. All accounts and sub-brands in a brand must reside in the same database as the brand account. To process payments in a branded environment, you must be logged in to Payment Tool as the root user. After you are logged in, you can only create and change payment batches in the brand you select from the Active Brand list. See Payment Tool for more information.
Brand Manager
Customer Center
Event Browser
G/L IDs
Invoice Browser
Payment Tool
Understanding Brands
Table 181 (Cont.) Branded Data Behavior Branded data Pricing Center Branding behavior Pricing Center is brand-aware based on the login of the brand administrator; the price list displayed in the tool is for that brand. You cannot switch between brands after you log in to Pricing Center. All pricing components, including products, deals, plans, plan lists, and price lists, are brand aware; brands cannot share pricing components. Only the brand administrator for a brand can create the price list for that brand. See "Creating a Price List for Brand Accounts". Self-Care Manager registration You can create a customer self-care home page for each brand in your system. Each self-care home page includes code that specifies the brand to use when displaying account information. See "About registering customers". Host administrators and brand administrators log into Pricing Center and use Zone Mapper to create zone maps for pricing and save them to a specific brand.
Zone Mapper
System-Wide Information
Data that cannot be separated according to a brand should be handled only by the host administrator because all brands access and use the same data. System-wide applications and objects include the data shown in Table 182:
Table 182 System-wide Data and Branding Behavior Branding behavior The host administrator should run billing scripts, such as pin_bill_day, for all brands at one time. Billing for one brand is possible, but it is resource intensive. See "Running Utilities with a Branded Database" for details. Configuration information such as ratable usage metrics (RUMs), currencies, and tax supplier IDs are system wide, with the exception of the following: /config/glid, /config/invoice_templates, and /config/invoice_events. These can be configured for a specific brand. See "Setting Up the General Ledger to Support Brands" and "Setting Up Invoicing to Support Brands". All brands must use the payment processor connected to the credit card data manager; for example, Paymentech. See "About BRM-initiated payment processing" in BRM Configuring and Collecting Payments for more information. The BRM object schema is a shared resource between all brands; therefore, only the host administrator should modify it. By default, FM policy opcodes are not brand-aware; however, some policy opcodes will pass brand-aware data. Although service names are system wide and all brands can share the same service object, each brand uses a different instance of the service.
Configuration information
Developer Workshop and the data dictionary Facility Module (FM) policy opcodes Services
Table 182 (Cont.) System-wide Data and Branding Behavior System-wide data Taxation Remittance for service providers Branding behavior All brands in a BRM system must use the same taxware calculation software. A brand account cannot contain a remittance product; however, you can set up a separate remittance account in a branded BRM system. The account receiving remittance can be in the same brand as the accounts paying the remittance funds. The remittance account can also be part of another brand or a system-level account.
Create sub-brands in Brand Manager. For example, if a brand has regional offerings or subsidiary brands, you can create hierarchies of sub-brands within the parent brand. Create account groups in Customer Center. For example, you might want to assign different CSRs to different groups of accounts by using access privileges.
Figure 181 shows how a brand hierarchy might be organized, with a mixture of brands, sub-brands, and account groups:
Figure 181 Brand Hierarchy
Enterprises. However, the East Coast Enterprises brand and the Last Chance Internet brand can each contain a sub-brand named Global Music. This is valid because the Global Music sub-brands are part of different brand hierarchies that have different parent brands.
Note:
The same rules apply for sponsor groups. You cannot have two sponsor groups with the same name under one parent brand.
You cannot transfer a customer from one brand to another brand or to a non-branded mode. You cannot move an account from a non-branded to a branded mode. You can move an account from one account group to another account group within a brand, but not between brands. You can drag nonpaying (subordinate) child accounts and paying (nonsubordinate) child accounts between account groups within the same brand.
You plan on moving accounts in and out of different clusters. Moving an account from one brand to another, or from a non-branded environment to a brand, is prohibited by branding and requires the accounts to be closed and recreated, which is a time-consuming process. You will share BRM pricing data such as products, deals, and plans, or general ledger revenue reporting. This eliminates the need to copy the same pricing component into each brands price list and then maintain multiple instances of that component. You need strict divisions between account hierarchies and want to segregate data into isolated groups. You will have sponsored accounts. You cannot apply sponsored rates across brand boundaries, and you cannot apply sponsored rates to a parent brand for accounts in a sub-brand.
You must have access to the parent brand, either as a brand administrator or through access privileges. See "Controlling Access to Top-Level Brands". You must create a custom price list and commit it to the parent brand before you create sub-brands. Brand administrators must have service/admin_client permissions to log into Configuration Center and create brands. Therefore, when host administrators create brands in their BRM system, they must include service/admin_client in the default plan for the brand. This service gives brand administrators access to BRM client tools. Similarly, when creating sub-brands, brand administrators must include service/admin_client in the default plan for the sub-brand if they want sub-brand administrators to create additional sub-brands.
You can change most information for a brand, but you cannot change the plan or logins for brand managers.
The host administrator has root access to the entire BRM system. Brand administrators have full access to their brand and any of its sub-brands. Brand administrators are the login names entered as part of creating a brand. You can create one or more brand administrators when you create a brand, but you cannot change or delete them later.
Other BRM users, such as CSRs, must be part of a brands access group to work with customer accounts and other data for that brand. For information on creating access groups, see "Controlling Access to Top-Level Brands". An access group includes:
A single brand, sub-brand, or account group The logins of one or more BRM users
You can assign a BRM user to one or more access groups. When using Customer Center or other BRM tools, you only see and work with data that belongs to the brand or account group you have access to. In Customer Center, you can access multiple brands concurrently if you have proper permission.
Note:
Only the brand administrator can create a price list for a brand. Access group members do not have this ability.
Note:
If you have access to a brand, you also have access to its sub-brands. You do not have implicit access to parent brands in your brand hierarchy. Access privileges also apply to creating access groups. You need privileges to work with a brand to set up access groups for sub-brands or account groups within that brand. In Customer Center, CSRs belonging to multiple access groups can open accounts from multiple brands concurrently. You can add CSRs to an access group only if the CSRs already have access to a brand or account group within the hierarchy of an active brand. If the CSR was created in another brand hierarchy, the administrator of the parent brand must add the CSR to the desired brand.
This access level Brand Account Administrator The users login ID is used to create a brand.
Access Group Member The CSRs login ID is added to an access group for a brand or account group. Brand Member The CSR account was created in a brand, but the CSR is not a member of an access group.
admin_client service for any brand to enable access to BRM client applications. pcm_client service if you use applications, such as testnap, that log in to BRM through this service.
When you create a plan in Pricing Center, you can give the plan any name, but you must include it in a plan list named brand. Figure 183 shows a brand host price list that contains the brand plan list. The plan list contains a plan named Brand Plan that contains two services to create top-level brands with.
Figure 183 Brand Host Price List
After the BrandHost price list is committed to the BRM database, the plan Brand Plan will be displayed in Brand Manager.
Note:
Unlike Customer Center, Pricing Center limits access to multiple brands. When logging in to Pricing Center, you can only see the price list for the brand whose login and password you used. Therefore, when the host administrator logs in to Pricing Center as root, the host administrator can only see the Brand Host plan, and not the price plans created by each brand. To see a brand price list, the host administrator must log in to Pricing Center by using the brand administrators login and password.
Brands and sub-brands can also be created in the system currency, even if the parent brand has a different primary or secondary currency. For more information on account currency and system currencies, see "Managing System and Account Currencies".
All accounts you create in a brand are created with the same status as the brand. Inactivating a brand inactivates all accounts in the brand. It does not inactivate the sub-brands or their accounts. A brand and all of its accounts can be reactivated if no changes were made to the brand or accounts in the brand after the brand was inactivated. If you inactivate an account before inactivating its parent brand, the account will be reactivated when the brand is reactivated. If desired, you must manually deactivate it again by using Customer Center. Inactivating a brand moves all closed accounts in the brand to inactive status.
Because the service names are different, the login name can be the same because the actual service is not shared between brands. But, if you use the same service name across brands, the login names must be unique across all brands that use that service name; it is not sufficient that the service instances be unique to a brand.
Tip: Use a generic naming convention for services to limit the transfer of company-specific information among brands. Notice that the services in the example are named /service/ip/ISP_* rather than the company name, such as /service/ip/A1.
See "Creating custom fields and storable classes" in BRM Developer's Guide for more information on creating service subclasses. If you do not want to duplicate services across brands, you can modify the login policy to append the brands domain name to the login name when a customer registers. For more information, see "Adding or changing login options" in BRM Developer's Guide.
Although it is not recommended, you can configure the brand account to handle A/R. Open the brand account in Customer Center and set up the billing and payment information. Then, when you make a customer account nonpaying (subordinate) to the brand account, change the nonpaying child accounts billing date to match the brand bill units billing date.
19
19
This chapter describes how to configure a Oracle Communications Billing and Revenue Management (BRM) database to use branding. The tasks described in this section are generally done by the host administrator. You must have the Brand Manager component to create and use brands.
Before creating a brand, you must set up your BRM system to use branding and you must create a brand plan list.
To create a top-level brand, you must have root access to BRM. To create a sub-brand, you must have access to the parent brand, either as a brand administrator or through access privileges.
Starting and stopping all system processes and services. Creating and changing BRM objects in the data dictionary. See "Creating custom fields and storable classes" in BRM Developer's Guide. Defining resources, ratable usage metrics (RUMs), and other pricing components. See "About creating a price list" in BRM Setting Up Pricing and Rating. Defining the default general ledger (G/L) ID account maps and G/L reports. See "Reporting by brand" in BRM Reports. Setting up invoicing. See "Designing and generating invoices" in BRM Designing and Generating Invoices. Setting up Web registration for customers. Running billing. See "Running billing utilities" in BRM Configuring and Running Billing.
Brand-related tasks
Activating Branded Service Management Defining a Price List for Brand Creation Controlling Access to the Data Dictionary Creating Brands Giving Permissions to the Brand Administrator Controlling Access to Top-Level Brands
Caution!:
After you make branded service management active in your BRM system, do not try to change your system back to a non-brand system. You can corrupt data if you do this.
Open the CM configuration file (BRM_Home/sys/cm/pin.conf). BRM_Home is the directory in which you installed the BRM software. Change the dm_attributes entry to include these parameters:
- cm dm_attributes database_number assign_account_obj, scoped, searchable
If your BRM system uses multiple databases, you need a dm_attributes entry for each database. See the configuration file for more information about this entry.
3.
4. 5.
Only a brand administrator should commit a price list to BRM for a brand.
Log in to Pricing Center as the root user. Define the plans and add services to them.
Important:
The plan you use to create brands must contain the admin_client service; without it, the brand administrator cannot use BRM client tools such as Configuration Center. If the brand administrator will use BRM developer applications such as testnap, also include the pcm_client service in the plan.
3. 4. 5. 6.
Create a plan list named brand; for the plan list type, click new. Add the brand plans to the plan list. Save the price list to the BRM database. Create brands by using Brand Manager. See "Creating Brands".
For detailed instructions on creating a price list, see Pricing Center Help.
Creating Brands
Tip: To configure each brand with a default price list, commit the same price list to BRM every time, but use the brand administrator logins specific to each brand.
Creating Brands
Note:
After you create a brand, you cannot change the brand plan.
For details on these steps, see Brand Manager Help. To create a brand:
1. 2. 3.
Using Pricing Center, create a plan list named brand and commit it to the BRM database. See "Defining a Price List for Brand Creation". Log in to Configuration Center as the root user. Click the icon for Brand Manager shown in Figure 192:
Creating Brands
4.
Click New Brand and specify the following brand account information:
A unique brand name and the URL for the brand Web site.
Note:
Brand names must be unique within a brand hierarchy; each sub-brand under the same parent brand must have a different name. The brand URL is optional.
The currency used by the brand accounts. If you choose an EMU or the euro currency for the primary account currency, a Secondary Currency field displays. You must choose a second account currency for the brand.
(Optional) The brand status. (Optional) The brand expiration date. The brand plan. The service login names and passwords for brand administrators.
After you define the basic account information, you must add a billing contact to the brand.
5.
The billing contact information is required, but you can also define additional contacts. For more information, see Brand Manager Help.
First and last name. Email address. Company name. Mailing address. (Optional) Phone number.
Tip: Brands are identified in the Customer Center Account Navigator and in the Search Results lists by the account number and the billing contacts last name and first name, not by the brand name. To display accounts by brand name, enter the brand name in the billing contacts Last Name field.
6.
Use Access Privileges, another Configuration Center application, to assign additional BRM users permission to work with a brand. For more information, see "Controlling Access to Top-Level Brands".
Creating Brands
Click the Brand Manager icon on the Configuration Center toolbar. Because this is the first brand created for this system, Brand Host (the BRM system) is the only item on the active brand list, and it is already selected.
2.
Brand Name: East Coast Enterprises Brand URL: www.ecoastent.com (In a multidatabase environment) Database: 0.0.0.1 Currency: US Dollar Status: Active. By default, all accounts you create in the brand will be created with this status. Expiration Date: February 1, 2005 Plan. The brand plan is CSR in this example Service: admin_client Login: ece Password: ece
Note: The brand administrator can change the login name and password at a later date by using Customer Center.
Figure 193 shows the General tab for the host brand after you enter the data:
Creating Brands
Note:
The Save button is inactive because billing contact information needs to be entered on the Contacts tab. You cannot save the brand until all required data is entered.
3.
Click the Contacts tab and enter information for the billing contact.
Note:
You can enter other contacts, but billing contact information is required. These contacts are only for your information and are not used for billing purposes. The phone numbers are optional. Brands appear in Customer Center as regular accounts but are identified in the Customer Center Account Navigator and in the Search Results lists by the account number and the billing contacts last name and first name, not by the brand name. To display brand accounts by brand name, enter the brand name in the billing contacts Last Name field.
4.
Click Save.
Controlling Access to Top-Level Brands Giving Permissions to the Brand Administrator Setting Up a Customer Center Search Filter for Access Group Owners Setting Up Invoicing to Support Brands Setting Up the General Ledger to Support Brands Setting Up Reports to Support Brands Setting Up Web Registration to Support Brands Setting Up Payment Methods for Brands Running Utilities with a Branded Database
This restriction is not true for Customer Center; you can open accounts from any brand that you have permission to access without having to select a specific brand. As a host administrator, if you know the brands in your database will be mutually exclusive and maintained by specified CSRs or administrators, you do not need to create an access group for each brand because access across brands is not required. You only set access permissions when you have one customer service representative (CSR) who administers multiple brands.
Use Access Privileges, a component of Business Configuration Center, to give BRM users access to a given brand or account groups. For more information on permissions and access groups, see "About Granting Access to Brands". To enable access to top-level brands:
1.
If you are a brand administrator controlling access to a sub-brand in your brand, log in to Configuration Center by using your administrator login and password.
2.
3. 4.
Click Access Group tab. Enter a name and select one brand, sub-brand, or account group for the access group from the tree as shown in Figure 195. The following example creates the access group for the brand brandB:
5. 6. 7.
Click Save. Click the Access Group Members tab. Search for login names belonging to the admin_client service. Figure 196 shows a search for all login names for the admin_client service.
Tip: You typically add logins for the admin_client service to an access group, so this service is available by default. If you want to add logins from another service, such as pcm_client, use the Configure button to add that service to the list of available services.
8.
Select a login from the Search Results list to include in the access group, and then click Add. In this example, the login name B_admin now has access privileges to brandB when logging in under the admin_client service. This login name can create and modify customer accounts for Brand1 in Customer Center. You can add more login names now or later.
9.
Click Save.
Log in to Configuration Center. Click the icon for Access Privileges as shown in Figure 197:
3. 4. 5.
Perform a wildcard search for an access group by using the asterisk (*). Select the access group ACL Group for Root Access. Add users as required. See "Controlling Access to Top-Level Brands".
To give users access only to root-level accounts and not to brand accounts, see "Limiting Users to Accessing Root-Level Accounts Only". For more information on the root access group, see "About the Root Access Group".
Add the root accounts to an account group. Create an access group for the account group. Add the CSRs to the access group.
1. 2. 3. 4. 5.
Log in to Customer Center as root and open the brand administrator account. Choose Edit - Permission. Select a permission string from the table in the dialog box. Select /accounttool/permissions and select Read/Write. Give the brand administrator other necessary permissions and save the account; for example, you might give the brand administrator permission to credit an account. Click Change Entry. Give the brand administrator other necessary permissions and save the account; for example, you might give the brand administrator permission to credit an account. Click Save.
6. 7.
8.
If you make any changes to the invoice template or the events displayed in the template, you must stop and restart the CM.
See "Designing and generating invoices" in BRM Designing and Generating Invoices for information on customizing templates.
Note:
If the brands in your system require customized templates that differ significantly, you can modify the PCM_OP_INV_POL_ FORMAT_INVOICE_HTML policy opcode to load brand-specific data into the brand templates. For example, by adding a brands company address information to the _CUSTADDR_ tag, you can generate a custom invoice with each brands corporate address.
G/L IDs are stored in a text file, and brand permissions cannot be set on them. Therefore, brand administrators should set operating system access permissions on the G/L ID file to deny other brands from reading and changing the data.
See "About collecting general ledger data" in BRM Collecting General Ledger Data for information on setting up G/L IDs.
Note:
Before you create Web pages for multiple brands, you need to define access privileges. See "Controlling Access to Top-Level Brands".
You must install, configure, and certify the BRM interface to a supported credit card service before you define the merchant numbers for brands. The interface to the credit card services is provided with the default BRM installation.
Not all utilities support branding; many do not. For more information, see the documentation for the utility you are using.
Caution!:
The host administrator should run billing for the entire database at the same time. Running billing for a particular brand is not recommended because it is very resource intensive and slows system performance.
Open the configuration file for the utility. For example, to run billing for a specific brand, open the pin.conf file in BRM_Home/apps/pin_billd. Replace the login name and password with the brand administrators login name and password:
- nap login_name brand_administrator_login - nap login_pw brand_administrator_password
3. 4.
Run the utility, or run the script that runs the utility. When the utility has finished, repeat this procedure for each brand, or change the login name and password back to the default host login and password.
Important:
You can create brand-specific configuration files; for example, pin.conf.brand_a and pin.conf.brand_b.
To create a /group/acl object, use the PCM_OP_PERM_ACL_GROUP_CREATE opcode. 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 the PCM_OP_PERM_ACL_ GROUP_DELETE_MEMBER opcode. To modify the attributes in a /group/acl object, such as the ACL name, brand or group account, or list of authorized service types, use the PCM_OP_PERM_ACL_ GROUP_MODIFY opcode. 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.
Important:
Deleting an ACL does not delete the brand account or affect services. It only removes the ACL.
To find all ACLs to which a CSR or member belongs, use the PCM_OP_PERM_ FIND opcode. See "Finding CSR Membership". To determine which brand or account group to display in a client application, use the PCM_OP_PERM_GET_CREDENTIALS opcode and the PCM_OP_PERM_ SET_CREDENTIALS opcode. See "Displaying ACLs in Multi-Branded Applications".
The application displays a list of available brands and bill units, along with the currently active brand or group. The CSR selects one brand or bill unit to access. The client application retrieves the connection scope for the selected brand or bill unit. The client application displays only those accounts in the selected brand or bill unit.
For more information, see "Adding branding to your application" in BRM Developer's Guide. You use the following opcodes to determine which ACL to display in a client application:
Use PCM_OP_PERM_GET_CREDENTIALS to retrieve all ACLs that are authorized for a particular client application, along with the currently active ACL. Use PCM_OP_PERM_SET_CREDENTIALS to set the connection scope for the specified ACL.
20
20
Managing Brands
This chapter describes how to create and manage multiple brands in a single Oracle Communications Billing and Revenue Management (BRM) system. The tasks described in this section are generally done by a brand administrator after the host administrator configures the BRM database for brands. You must have the Brand Manager component to create and use brands.
Creating a Price List for Brand Accounts Changing Account Defaults for a Brand Creating a Brand-Specific Web Page Defining a Brand-Specific Invoice Defining a Brand-Specific General Ledger System Defining Reports for a Brand Creating CSR Accounts for a Brand Creating Sub-Brands Accessing Branded Customer Accounts Processing Payments for Brand Accounts Inactivating or Closing a Brand Preventing Duplicate Brand Names Changing the Brand of an Account by Using a Custom Application
Create a price list in Pricing Center that includes a plan list of type new named CSR.
2.
Use the brand administrator login name and password when you commit the price list to BRM. This saves the price list to the brand.
Note:
You can see a brand administrators login name by opening the brand in Brand Manager.
The payment method. The default is prepaid. The minimum and maximum amounts that a CSR can credit or debit an account. The minimum and maximum amounts that a CSR can adjust payments to an account.
For information on changing account defaults, see "Setting Up Permissions in BRM Applications" in BRM System Administrator's Guide.
A brand can contain only one template. You can create a separate template for each brand, but not for an access group.
See "Designing and Generating Invoices" in BRM Designing and Generating Invoices.
In a branded environment, the only G/L IDs you can use are those defined by the host administrator when the BRM database is configured. You are limited to these IDs, but you can map them to any G/L accounts in your external system. For information on defining a brand-specific general ledger system, see "About Collecting General Ledger Data" in BRM Collecting General Ledger Data.
Before you can define reports for your brand, the host administrator must install and configure Oracle Business Intelligence Publisher. See "Installing BRM Reports" in BRM Reports.
The BRM Reports package includes brand-configured versions of the BRM base reports.
Log in to Customer Center by using the brand login name and password. Create the CSR account.
Note: Select the CSR plan to add the admin_client service to the account.
3. 4.
Give the CSR permissions. See "Setting Up Permissions in BRM Applications" in BRM System Administrator's Guide. Add the CSR to the access group for each brand you want the CSR to access.
Note: Before brand administrators can give account permissions to CSRs, the host administrator must give brand administrators permission to set account permissions. See "Giving Permissions to the Brand Administrator".
For more information on CSRs, see "About Managing Customers" in BRM Concepts The CSR account appears in Customer Center as a child account of the brand administrator account. If you want, you can move the CSR account to the same level as the administrator account by dragging the account icon.
Creating Sub-Brands
Creating Sub-Brands
To create a sub-brand, log in to Configuration Center by using the brand administrator login name and password. See "Creating Brands" for detailed instructions on creating sub-brands.
Note:
There is no limit to the number of sub-brands you can create; however, sub-brands in the same brand hierarchy must have unique names. Sub-brands in different brand hierarchies can share the same name.
For example, the brand East Coast Enterprises cannot have two sub-brands named Sales Division. However, it can have a sub-brand named Joannes Toys, and each of these brands can contain a sub-brand named Sales Division.
You must have the Branding component of BRM to use Access Privileges.
When a CSR logs in to either tool, the word Self appears in parentheses after the name of the brand to which the CSRs BRM account belongs. A CSR might have access privileges to multiple brands, but the CSR account belongs to only one brand. By default, CSRs can modify only the customer accounts they create; they cannot access accounts created by other CSRs. To enable CSRs to access all accounts in a brand, you must add them to the access group for the brand. Brands appear in Customer Center as regular accounts, but they are identified by the account number and name of the billing contact, not by the brand name.
1. 2. 3. 4. 5.
Log in to Customer Center by using the brand login name and password. Click Search, which opens the Search Accounts dialog box. From Brand Selector, choose the brand to open. Enter the search criteria. Click Search.
Note:
You cannot move a customer account to a different brand. You must first close the account in the old brand and then recreate the account in the new brand.
Log in to Payment Tool as a brand administrator or as a CSR with access privileges. Click Select Brand and choose the brand to work in. Process payments as you normally would.
When you reactivate a brand, all customer accounts in the brand are also reactivated, regardless of whether they were inactivated or closed independently from the brand.
See "About Closing, Inactivating, and Reactivating Brands" for more information.
The PCM_OP_CUST_COMMIT_CUSTOMER opcode calls the PCM_OP_CUST_SET_ BRANDINFO opcode when a brand account is created. PCM_OP_CUST_SET_BRANDINFO calls the PCM_OP_CUST_POL_SET_ BRANDINFO policy opcode for any user customizations, such as preventing duplicate brands. To customize brand assignment, use the PCM_OP_CUST_POL_SET_BRANDINFO policy opcode. This opcode allows you to customize the error information or information about the brand returned to PCM_OP_CUST_SET_BRANDINFO. the PCM_OP_CUST_POL_SET_BRANDINFO policy opcode also includes hooks for setting site-specific information.
Part III
Part III
Part III describes how migrate customer accounts from legacy databases. It contains the following chapters:
Understanding Conversion Manager Installing and Configuring Conversion Manager Mapping Legacy Data to the BRM Data Schema Migrating Data by Using New and Extended Storable Classes Loading Legacy Data into the BRM Database Migrating Legacy Data into BRM Table Partitions
21
21
This chapter provides an overview of Oracle Communications Billing and Revenue Management (BRM) Conversion Manager. It describes the process of converting data from a legacy database to the BRM database.
Important:
Conversion Manager is an optional component, not part of base BRM, and requires a separate license.
Account data, such as the customers name, address, profile, and discount information. Service data, such as the services subscribed to by the accounts. Product data, such as products purchased by the accounts. Billing data. Account hierarchy data. Balance data, including data for all resources. When data is migrated, rollover events can use the balance data to manage rollovers.
You can load account and balance data together, or you can load account data first and balance data second. All account data for an account must be loaded before loading balance data. Before migrating data, do the following:
Create a price list that applies to the migrated data before migrating account and balance data. Migrated data needs to reference the price list objects in the BRM database. Make sure that cycle arrears fees, billing-time discounts, and rollovers have been processed in the legacy system.
When the accounts are migrated, cycle forward fees and discount grants (for example, free minutes) are applied. However, all delayed events are handled in the current bill.
Note:
The following features are not supported by Conversion Manager: Brand management Auditing
Understanding the data in the legacy system and deciding how to convert it to the BRM database. Mapping the data in the legacy database to the BRM database. To do so, you create XML files, which are validated by the Conversion Manager XSD schema files. Migrating the data to the BRM database by using the pin_cmt utility. To migrate data: Import data into the BRM database. The data is hidden from BRM processes. Deploy the staged data to the production area.
See "Loading Legacy Data into the BRM Database" for more information.
Important:
Conversion Manager does not include a utility for extracting legacy data into XML files. You need to develop your own extraction utility or obtain it from third-party sources.
Conversion Manager converts data from any type of legacy database; for example, Oracle. To map data from the legacy database to the BRM data schema, you need a thorough understanding of the legacy data and how BRM stores data.
If your legacy data includes data not currently supported in BRM, you can create new storable classes, or extend storable classes, to support the custom data. You can then extend the Conversion Manager XML schema to migrate the data. See "Migrating Data by Using New and Extended Storable Classes". You can configure data enrichment to allow system-wide values to be bulk inserted and to provide batch controls for operational integrity.
First, you import the data into the BRM database. When the data is imported, it is hidden from BRM processes, so it is not part of your production system. (Data is hidden by changing the database number section in the BRM object ID (POID) of each imported object. The database number is set to a number defined in the infranet.cmt.dbnumber entry in the Infranet.properties file for the pin_cmt utility; for example, 0.0.0.12.) When you import data, you specify a stage ID. This allows you load data in stages; for example, you can load a specific type of account first. A single database can include multiple stages.
After the data is imported, you deploy the data. When you deploy data, the imported data is exposed as production data. You control which accounts are deployed by entering the stage ID that you used when importing the data. In addition, you specify the billing day of month (DOM). Therefore, only those accounts with the specified stage ID and DOM are deployed. After the data is deployed, the database number in the POID is changed to the actual database number, and the data becomes available for use by BRM processes.
Note:
Events that apply to a migrated account are not processed until the account is deployed. When data is deployed, the database number used is defined in the infranet.cmt.targetdbnumber entry in the pin_cmt utility Infranet.properties file. By default, the number is 0.0.0.1. File processing data, such as the file name and batch ID, is stored in the /batch/cmt object.
When accounts are deployed: The bill cycles are started. Cycle fees are applied. If you use a multidatabase system, the uniqueness table in the primary database is updated.
Important:
After deploying your imported accounts, stop and restart Pipeline Manager to send new account data to Pipeline Manager.
If you have a multidatabase system, make sure the stage IDs are larger than the database IDs. For example, if you have a database with the number 0.0.0.5, use stage IDs larger than 5.
Load account data before loading balance data. Load parent accounts before loading child accounts.
22
22
System Requirements
Conversion Manager is available for the Solaris and Linux operating systems and for the Oracle database.
Software Requirements
Before installing Conversion Manager, you must install:
Third-Party software, which includes the libraries and JRE required for installing BRM components. See "Installing the Third-Party Software" in BRM Installation Guide. BRM. See "Putting Together Your BRM System" in BRM Installation Guide. Oracle 10g or Oracle 11g. libocijdbc11.so. Conversion Manager requires the use of this OCI Instant JDBC Library.
Information Requirements
You need the following information about your existing BRM system during the Conversion Manager installation:
Database alias name of the staged database. Database port and number for the staged database. Database user name and password for the staged database. Database alias name of the primary database. Database port and number for the primary database.
22-1
If you have already installed the product, features that are already installed cannot be reinstalled without uninstalling them first. To reinstall a feature, uninstall it and then install it again.
If you download to a Windows workstation, use FTP to copy the .bin file to a temporary directory on your UNIX server. You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid Out of Memory error messages in the log file. For information, see "Increasing Heap Size to Avoid Out of Memory Error Messages" in BRM Installation Guide.
2.
Go to the directory where you installed the Third-Party package and source the source.me file.
Note:
You must source the source.me file to proceed with installation, otherwise suitable JVM not found and other error messages appear.
Bash shell:
source source.me.sh
C shell:
source source.me.csh 3.
You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.
4.
Follow the instructions displayed during installation. The default installation directory for Conversion Manager is /opt/portal/7.5.
Note:
The installation program does not prompt you for the installation directory if BRM or Conversion Manager is already installed on the computer and automatically installs the package at the BRM_Home location. BRM_Home is the directory in which you installed the BRM software.
5.
Go to the directory where you installed the Conversion Manager package and source the source.me file: Bash shell:
source source.me.sh
C shell:
source source.me.csh 6.
Many of the entries in the Infranet.properties file include default settings that are applicable for testing your data mapping; for example, the number of threads that the pin_cmt utility uses. You can change the settings when you load data into the production system.
In addition, you need to edit the pin.conf file for the cmt_mta_cycle_fees utility. This utility is run automatically by the pin_cmt utility to apply cycle fees. The pin.conf file is in BRM_Home/apps/cmt. It includes the standard connection parameters and multithreaded application (MTA) performance setting. You can also specify to not apply cycle fees to accounts. See "Applying Cycle Fees to Deployed Accounts".
where jar_A:jar_B:jar_C:jar_D is the list of Java class JAR files. Oracle library references are appended at the end.
22-3
Include all entries on one line with no line breaks. Separate JAR entries with a colon. Do not include any spaces in the list of JAR files. The number of elements is limited only by command-line length (approximately 8 kilobytes on most machines). The following shows an example:
BRM_Home/jre/bin/java -Dfile.encoding=utf-8 -cp "BRM_Home/apps/cmt/cmt.jar:BRM_ Home/jars/xercesImpl.jar:BRM_Home/jars/xmlParserAPIs.jar:BRM_Home/jars/pcm.jar:BRM_ Home/jars/pcmext.jar:BRM_Home/apps/cmt" com.portal.cmt.Cmt $1 $2 $3 $4 $5 $6 $7 $8 $9
Open the BRM_Home/apps/cmt/Infranet.properties file in a text editor. Add the following entry. Provide the required value for n. See Table 221.
infranet.cmt.timestampvalidation = n
Note:
If you provide an invalid input for infranet.cmt.timestampvalidation, BRM replaces that value with the default value (1).
3.
view accounts according to their stage ID. You can configure multiple scoped DMs, one for each staging area. In addition to configuring scoped DMs, you also need to configure the production Oracle DM to support DM scoping. A BRM system that includes scoped DMs is called a scoped system. To configure a scoped system:
1.
Run the pin_convert_nonunique.sql script in BRM_Home/apps/cmt/scripts. This script drops unique constraints for indexes used in account creation.
Note: By default, the pin_convert_nonunique.pl script uses PINX00 to identify tablespaces for indexes. If you use a name other than PINX00, edit the pin_convert_nonunique.pl script to change PINX00 to your tablespace name.
2.
Run the BRM_Home/sys/dd/data/cmt_copy_group_planlists_oracle.sql stored procedure. This procedure duplicates the /group/plan_list object with the staged database number, which allows you to create accounts by using Customer Center. The stored procedure uses the following parameters:
Database number; for example, 5 Return code (number) Return message (varchar2(100))
Create a pin.conf file for each scoped Oracle DM. To do so, edit the Oracle DM pin.conf file in BRM_Home/sys/dm_oracle. Edit the following entries:
Set the scoped_system entry to 1. This enables database scoping. Set the production_system entry to 0. This identifies the DM as a scoped DM. Set the staging_db_number entry to the stage ID used for importing data. If you use a multidatabase system, the stage ID must be larger than the largest database number. Include the table names for the data you are importing in the scoped_ exception_tables entry.
22-5
4. 5.
Repeat the DM pin.conf configuration for each scoped DM, using a different stage ID for each one. Configure the production Oracle DM by editing the following entries:
Set the scoped_system entry to 1. Set the production_system entry to 1. This identifies the DM as the production DM. Include the table names for the data you are importing in the scoped_ exception_tables entry.
Start the scoped DMs. Create a root account for each stage ID:
a. b. c.
Start the scoped Oracle DMs. Open the load_pin_acct script in BRM_Home/apps/cmt/scripts. Edit the first line of the script to point to a valid Perl path. For example:
/opt/portal/ThirdParty/perl/5.8.0/bin
d.
Edit the $dm_port entry to point to the Oracle DM port number. For example:
$dm_port = 22251
e.
Make sure the $db_no entry points to the production database. For example, if the production database number is 0.0.0.1, and the staged database number is 0.0.0.11, use the following entry:
$db_no = 0.0.0.1
f. g.
Save and close the file. Run the load_pin_acct script using the following command:
load_pin_acct -I pin_init_acct
Note:
The input flist used when the root account is created still refers to the production database number because the staging DM translates it to the staging database number.
8.
Stop and restart all Connection Managers and Oracle DMs used for accessing the staged data.
Infranet.properties File Entries to Enable Multidatabase Loading Description Enables or disables data migration in a multidatabase system. Enter true or false. Specifies the database name; for example, pindb1. Specifies the database login name. Specifies the database login password. Specifies the database number for the primary database; for example, 0.0.0.2.
To enable or disable XML validation, edit the infranet.cmt.preprocess.validation entry in the Infranet.properties file:
infranet.cmt.preprocess.validation = true
Use the infranet.cmt.avgnoofservices entry to specify the average number of services that each account owns. This entry reserves Portal object IDs (POID) for the objects that will be created by the pin_cmt utility. The default is 5. Use the infranet.cmt.avgnoofdevices entry to specify the average number of devices that each account owns. This entry reserves POIDs for the objects that will be created by the pin_cmt utility. The default is 2. Use the infranet.cmt.noofrecords entry to specify the average number of account records in each input XML data file. Use the infranet.cmt.dbnumber entry to set the staged database number; for example, 0.0.0.12. Use the infranet.cmt.dbname, infranet.cmt.userid, and infranet.cmt.passwd entries for the rest of the staged database information. Use the infranet.cmt.targetdbnumber entry to set the target database.
Note:
If an account owns more or fewer services or devices than the numbers you specify, the objects are still loaded.
22-7
You can specify the default credit limit profile by editing the infranet.cmt.creditprofile entry in the Infranet.properties file:
infranet.cmt.creditprofile = IndexID
Each credit limit profile is stored in a PIN_FLD_PROFILES array in the /config/credit_profile object. Replace IndexID with the index ID of the appropriate PIN_FLD_PROFILES array. In this example, you would replace IndexID with 3:
0 PIN_FLD_PROFILES 1 PIN_FLD_CREDIT_FLOOR 1 PIN_FLD_CREDIT_LIMIT 1 PIN_FLD_CREDIT_THRESHOLDS
ARRAY [3] allocated 3, used 3 DECIMAL [0] NULL DECIMAL [0] 133 INT [0] 0
You can assign a credit limit, credit floor, and credit threshold to each balance group when you run the pin_cmt utility. To do so, add the following XML elements to the input XML file that you import with pin_cmt:
The values specified in the input XML file take higher precedence than the value of the infranet.cmt.creditprofile entry in the Infranet.properties file.
If the infranet.cmt.31daybilling.forward entry is enabled, BRM performs forward billing if the billing day of month is greater than 28. If it is disabled, BRM performs backward billing. For more information, see "Using 31-day Billing" in BRM Configuring and Running Billing.
For more information, see "Setting Up Delayed Billing" in BRM Configuring and Running Billing.
Validate the files with the Conversion Manager physical XML schema. Use the proper tab (\t) and new line (\n). Do not use spaces. Make sure all the required tags are present in the XML.
one.xml 1 & two.xml 1 & three.xml 1 & four.xml 1 & five.xml 1 &
While running the script, measure the CPU load and time taken by the pin_cmt utility for this entire batch. You can then increase the number of pin_cmt instances until the CPU load reaches 90%.
infranet.cmt.minconns
22-9
infranet.cmt.maxconns infranet.cmt.timeout
For example:
infranet.cmt.minconns = 15 infranet.cmt.maxconns = 30 infranet.cmt.timeout = 1000
For more information, see "About Connection Pooling" BRM System Administrator's Guide.
In the BRM_Home/apps/cmt/pin.conf file, change the pin_mta loglevel entry to 1. In the BRM_Home/apps/cmt/Infranet.properties file, change the infranet.log.level entry to 1.
System Resources
Migrating data can use a lot of system resources. Performance can depend on:
Set the following entries to correspond to the amount of data in the XML files. The infranet.cmt.noofrecords entry specifies the number of accounts.
infranet.cmt.noofrecords infranet.cmt.avgnoofservices infranet.cmt.avgnoofdevices = 1000 = 5 = 2
Make sure there are enough connections in the staging database connection pool:
infranet.cmt.minconns infranet.cmt.maxconns infranet.cmt.timeout = 15 = 30 = 1000
Depending on your system configuration and load, your settings might be different.
When you use the flag direct=true, make sure the BRM user has DBMS_LOCK permission.
Specify the appropriate capacity settings for your system; for example:
pin_mta pin_mta pin_mta pin_mta children per_batch per_step fetch_size 5 500 1000 5000
22-11
23
23
It is beyond the scope of this chapter to describe your legacy data in detail because each system is unique.
Conversion Manager is an optional component, not part of base BRM, and requires a separate license.
Ensure that there are no extra spaces in the input XML file. If you need to indent text in the XML file, use the TAB key to add space.
Sample XML files for each type of data are available in BRM_Home/apps/cmt/sample_ data. BRM_Home is the directory in which you installed the BRM software.
A set of conceptual files that you can use for mapping legacy data to BRM objects. These files are easier to read than the set of files used for converting data. A set of physical files that are used by Conversion Manager when converting data. These files are not as easy to read, but are written in a way that optimizes performance.
The difference between the types of files is how the XML tags are named. In the conceptual files, the XML tags use the same field names as the BRM object fields. For example:
Mapping Legacy Data to the BRM Data Schema 23-1
To set up mapping, you can use the easily-readable conceptual files to determine how to map data. Then you can edit the physical files, after you know how the data is mapped. The conceptual files are in BRM_Home/apps/cmt/schema_files/conceptual. The physical files are in BRM_Home/apps/cmt/schema_files/physical. Use the following physical XSD files to create your XML files:
Use the CMT_Subscriber.xsd file for subscriber data. Use the CMT_Balances.xsd file for balance data.
Tips:
Before you use the pin_cmt utility to migrate data, validate the XML files with the physical XSD files. Do not use spaces while generating the XML files. Use tabs (\t) and new lines (\n).
"Storable Class-to-SQL Mapping" in BRM Developer's Reference "Storable Class Definitions" in BRM Developer's Reference
Note:
Tables Affected by the Conversion Process Description Master account table that represents billable accounts in BRM. Only one row is added to this table for each account in BRM. Contains an entry for each tax exemption that applies to an account. Contains name and address information for accounts. There is one row for each name and address type (home address, work address, mailing address, and so forth). There must be at least one row in this table for each row in ACCOUNT_T. For example, you can have billing name and address information, technical contact name and address information, and sales name and address information.
ACCOUNT_T
ACCOUNT_EXEMPTIONS_T ACCOUNT_NAMEINFO_T
ACCOUNT_PHONES_T
Contains a phone number and a phone type for each account. There is one row for each phone type (up to seven types are defined, including home, work, fax, and pager). If there is no phone number information for an account, there are no rows in the table for the account. Stores the balance information such as dollars, free minutes, bytes, and frequent flyer miles for various resources in an account. A balance group includes one or more sub-balances for each resource. The sub-balance contains the current amount, resource type, validity dates for the resource, rollover data, and sub-balance contributors. Stores balance group data. Stores sub-balance data. Includes billing information, such as the amount due, amount adjusted, currency, and bill number. A /bill object is created at the end of a billing cycle. A /bill object is created for every account. The account receivable for a bill is stored in the /item objects that point to the balance groups associated with the bill. The /bill object points to the /account object, the accounts /billinfo object, and the /invoice object.
BALANCE_GROUP_T
BILLINFO_T
Stores all billing, payment method, accounting cycle, and hierarchy information necessary to bill an account. A /billinfo object is created for every account. If the billinfo is subordinate, the /billinfo object points to the parent account and the parent accounts /billinfo object. Stores information about devices. There is a separate /device object for every device managed by BRM. Generic data applicable to all devices is stored in the parent /device object. Subclasses such as /device/num store information specific to a particular device type. Stores device information specific to phone numbers managed by Number Manager. Stores device/service mapping data. Stores device information specific to SIM cards managed by SIM Manager.
DEVICE_T
Table 232 (Cont.) Tables Affected by the Conversion Process Table name EVENT_T Description Contains a row for each account that has a nonzero balance forward amount. This table stores data for every event that occurs for an account or service. In the case of conversion of an account that has a balance, you should add a row to reflect the posting of that balance. You also need to write an entry to this table for each entry you write to the EVENT_BILLING_DEAL_INFO_T and EVENT_BILLING_PRODUCT_ACTION_T tables. In addition, you can optionally add rows to this table to store past activity for an account. For example, use this table to add rows for importing past billing and payment history into BRM. These rows can be brought over as memo type events, which can be viewed in Customer Center, but they do not affect the current account balance (which should be calculated and posted separately). EVENT_BAL_IMPACTS_T EVENT_ESSENTIALS_T GROUP_T Stores event data. Stores event data. Represents collections of other storable objects that have an assigned set of shared attributes. This table is optional. If you use it at conversion time, one row must be added to this table if the account is a parent or sponsoring account. Rows for this table are optional and are included only for child accounts (that have a parent account) or for accounts that are members of a brand. During conversion, one row needs to be added to this table for each child account (regardless of the child accounts payment method). Indicates which accounts are group accounts. Rows for this table are optional and are included only for parent accounts that have at least one child account. Stores members of a resource sharing group. Stores charges of a resource sharing group. Stores discounts of a charge sharing group. Stores the profile data that is shared in a profile sharing group. Created to bundle events, this table summarizes billable item activity by type. Rows in this table are added for each row in the BILL_T table. In a conversion scenario, only one type of ITEM_T entry is important, the /usage item. Although there are others (cycle forward item, payment item, dispute item, and so on), they are normally not pertinent for conversion. For conversion, a default /item/misc is created to bundle events. Also, a service-level item is created during conversion only if the recreate ='/item/<item-type>' is specified in the input XML data. Stores general ledger (G/L) journal data. Stores ordered balance group data. Stores ordered balance group data.
GROUP_BILLING_ MEMBERS_T
GROUP_PERMITTEDS_T
Table 232 (Cont.) Tables Affected by the Conversion Process Table name PAYINFO_T Description Stores generic payment method information for an account. Only one row is added in this table for each row in ACCOUNT_T. In addition to a row in PAYINFO_T, there must also be a row added to the applicable payment method table. For example, you have to add a row to PAYINFO_INV_T if the payment method for an account is Invoice. Additionally, if you have created a custom payment method and a PAYINFO_paymentMethod_T table, where paymentMethod is the custom payment method, you must add a row to that table for each account with that payment method. PAYINFO_CC_T Contains a row for each account that has a payment method of Credit Card. This row is in addition to a row in PAYINFO_T. Note: This payment method assumes that you are using the BRM-provided FirstUSAPaymentech or FDC modules to process your credit cards or that the clearing house or bank you use can process the same information. If your credit card processing is significantly different, you might want to set it up as another payment method and store information on that payment method separately. PAYINFO_DD_T Contains a row for each account that has a payment method of Direct Debit. This row is in addition to a row in PAYINFO_T. Contains a row for each account that has a payment method of Invoice. Optionally, the table can also contain purchase order (PO) information. Contains profile information, if any. This table can be left empty if you decide not to convert profile information. You can populate only one row in this table for each row in ACCOUNT_T. Rows are added to this table only if rows are added to PROFILE_T, where customTable is the unique identifier you choose; for example, company name. For each row added to PROFILE_T, a corresponding row is added to PROFILE_ customTable_T. Contains profile information. Contains profile information. Contains profile information. Contains an entry for each discount owned by an account at the time of conversion. Contains an entry for each product owned by an account at the time of conversion. Stores generic service type information for accounts. There is one row in this table for each applicable service for each entry in ACCOUNT_T. In addition to a row in this table, a row must be created in the service type table, such as IP service or email.
PAYINFO_INV_T
PROFILE_T
PROFILE_customTable_T
Table 232 (Cont.) Tables Affected by the Conversion Process Table name SERVICE_ALIAS_LIST_T SERVICE_TELCO_T SERVICE_TELCO_ FEATURES_T SERVICE_TELCO_GSM_T UNIQUENESS_T Description Stores service aliases, used to identify customers by phone number. Stores telco service data. Stores telco service data. Stores telco service data. Stores data that enforces uniqueness of logins across different databases in a multidatabase environment.
AU_ACCOUNT_T AU_BAL_GRP_T AU_GROUP_SHARING_CHARGES_T AU_GROUP_SHARING_DISCOUNTS_T AU_GROUP_SHARING_PROFILES_T AU_GROUP_T AU_ORDERED_BALGROUP_T AU_ORDERED_GROUPS_T AU_PROFILE_ACCT_EXTRATING_DATA_T AU_PROFILE_SERV_EXTRATING_DATA_T AU_PROFILE_SERV_EXTRATING_T AU_PROFILE_T AU_PURCHASED_DISCOUNT_T AU_PURCHASED_PRODUCT_T AU_SERVICE_ALIAS_T AU_SERVICE_T AU_UNIQUENESS_T
24
24
Conversion Manager does not support extensions for all BRM classes. See "About Extended Classes for Migration".
Create the new or extended classes. See "About Extended Classes for Migration". Create XML files that include the migrated data. See "Creating XML Files for New or Extended Class Data". Create control files to add tables to the BRM database. See "Creating Control Files for Extended Classes". Run the pin_cmt utility as you would for migrating non-extended data. See "Loading Legacy Data into the BRM Database".
Important:
When you import data for new classes, you use a different pin_ cmt utility parameter (-import_custom). When you migrate data into custom classes, the pin_cmt utility performs the additional step of activating the custom data when it is deployed. Import all custom data before you deploy any data. The only exception is if all the custom data belongs to the root account; for example, custom system configuration data.
For example:
/service/extension1 /service/extension1/extension
/account /service (and extended service classes) /device (and extended device classes) /payinfo (and extended payinfo classes) /profile (and extended profile classes) /group/sharing/charges /group/sharing/discounts
When creating new or extended classes, follow the BRM standards and restrictions. For example:
You cannot nest substructs. An array can include an array, but no further levels are allowed.
Use the XML myExtension element for extended data. Use the XML NewClass element for new custom classes.
Use the myArray and mySubstruct elements for arrays and substructs in the extended data. Use the table attribute in each array and substruct to define the table that stores the data. Use the elem attribute in each array to define the index. Use the RefObj element to create links to other objects. To do so, use the ID of the object being linked to. For example:
<RefObj type ="/account"> 1234 </RefObj>
If the pin_cmt utility does not find the object being linked to, it reports a warning and inserts a null value in the Portal object ID (POID) being referenced.
Use the type attribute in all new and extended elements to define the type of data. The type attribute for a new class is defined in the base class element. For example:
<NewClass id="1243" type="/myclass" table="myclass_t" read="L" write="L" >
The type attribute for an extended class is defined in the base class element. For example:
<ActSrv id="771" type="/service/extended" precreate="/item/misc" global="true">
Example of Extending a Service Class Example of Extending A Device Class Example of Creating a New Class
For each type of extended information, use a different namespace to avoid collisions caused by using the same name myExtension.
If the extended information contains BRM extensions (for example, /service/x, /payinfo/x, /device/x, and /profile/x), include the custom XSD in the CMT_ Subscribers.xsd file. This allows the extended information to be validated along with the subscriber information. If the extended information includes a custom class (for example, /my_profile), the custom XSD does not need to be included in the CMT_Subscribers.xsd file. The extended information can be validated by the custom XSD file. Put the custom XSD file in the folder specified in the infranet.cmt.schema.location entry in the pin_cmt utility Infranet.properties file. By default, the folder is BRM_ Home/apps/cmt/schema_files/physical.
Important:
To enable XML validation, use the infranet.cmt.preprocess.validation entry in the pin_cmt Infranet.properties file. See "Enabling XML Validation".
New classes Substructs in new or extended classes Arrays in new or extended classes
When you create a control file, the name of the control file is used as the table name. For example, if you create a new class named /myclass, which includes a substruct named PIN_FIELD_MYSUBSTRUCT, the table name would be MYCLASS_SUBSTR_T. The control file name would be myclass_substr_t.ctl.
Important:
The order of columns in the control file must be the same as the order of columns in the table. The order of data in the XML input file must be the same as the order of data in the control file and table. While adding tables to the BRM database, ensure that the tables listed in the pin_cmt utility Infranet.properties file belong to the main class.
Example of Extending a Service Class Example of Extending A Device Class Example of Creating a New Class
Put the control files in BRM_Home/apps/cmt/ctl_files. Edit the pin_cmt utility Infranet.properties file.
For control files that add substruct and array data, edit the infranet.cmt.loaders entry. Add the control file names. For example:
infranet.cmt.loaders = account_t; account_nameinfo_t; ...; extended2_ substr1_t; extended_cust1_t; extended2_cycle_t;
For control files that add data for a new class, add the infranet.cmt.customtables entry. Add the table names, separated by semicolons. For example:
infranet.cmt.customtables = myclass_t;
Note:
In Developer Workshop, the extended /service class definition looks like this:
/service/extended CMT_ARRAY CMT_NAME PIN_FLD_ACCOUNT_TYPE CUST_ARRAY PIN_FLD_CYCLE PIN_FLD_CUSTOMER_TYPE PIN_FLD_CYCLE_DISC_AMT PIN_FLD_CYCLE_END_T
After loading the data, the extended fields are included in the stored object like this:
0 0 0 . . . 0 0 1 0 PIN_FLD_POID PIN_FLD_CREATED_T PIN_FLD_MOD_T POID [0] 0.0.0.1 /service/extended 11813 3 TSTAMP [0] (1083337746) Fri Apr 30 08:09:06 2004 TSTAMP [0] (1083338129) Fri Apr 30 08:15:29 2004
ENUM [0] 0 ARRAY [0] allocated 1, used 1 STR [0] "00491110102" SUBSTRUCT [0] allocated 2, used 2
STR [0] "abc" ENUM [0] 99 ARRAY [1] allocated 3, used 3 DECIMAL [0] 190 TSTAMP [0] (1075713735) Mon Feb ARRAY [1] allocated 1, used 1 ENUM [0] 190
2 01:22:15 2004
The following examples show the control files used for loading the data for the extended /service class. The substruct and arrays require new tables. The array tables include the columns REC_ID or REC_ID2; the substruct does not include these columns. Example control file for substruct
-- extended_substr1_t.ctl LOAD DATA APPEND INTO TABLE EXTENDED_SUBSTR1_T ( OBJ_ID0 INTEGER EXTERNAL TERMINATED BY ',', NAME CHAR TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"', TYPE INTEGER EXTERNAL TERMINATED BY ',' )
BY BY BY BY
BY BY BY BY
<Mnufr>Airtel2</Mnufr> <Mdl>A4IR124</Mdl> </Device> <myExtension> <myArray table="dev_extended2_t" elem="1"> <FldAmount type="integer">11</FldAmount> <FldDate type="date">2004-03-15T01:22:15-07:00</FldDate> </myArray> </myExtension> </DeviceInfo>
In Developer Workshop, the extended /device class definition looks like this:
/device/extended2 PIN_FLD_ENTRIES PIN_FLD_ENTRY_AMOUNT PIN_FLD_ENTRY_T
After loading the data, the extended fields are included in the stored object like this:
# 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 1 1 number of field entries allocated 14, used 14 PIN_FLD_POID POID [0] 0.0.0.1 /device/extended2 11811 0 PIN_FLD_CREATED_T TSTAMP [0] (1083337746) Fri Apr 30 08:09:06 2004 PIN_FLD_MOD_T TSTAMP [0] (0) <null> PIN_FLD_READ_ACCESS STR [0] "L" PIN_FLD_WRITE_ACCESS STR [0] "A" PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 1 0 PIN_FLD_DESCR STR [0] "" PIN_FLD_DEVICE_ID STR [0] "00982110309" PIN_FLD_MANUFACTURER STR [0] "Airtel2" PIN_FLD_MODEL STR [0] "A4IR124" PIN_FLD_SOURCE STR [0] "source2" PIN_FLD_STATE_ID INT [0] 0 PIN_FLD_SERVICES ARRAY [3] allocated 2, used 2 PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account 11806 0 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/extended2 11813 0 PIN_FLD_ENTRIES ARRAY [1] allocated 2, used 2 PIN_FLD_ENTRY_AMOUNT DECIMAL [0] 11 PIN_FLD_ENTRY_T TSTAMP [0] (1079342535) Mon Mar 15 01:22:15 2004
The following example shows the control file used for loading the data for the extended /device class:
LOAD DATA APPEND INTO TABLE DEV_EXTENDED2_t ( OBJ_ID0 REC_ID AMOUNT ENTRY_T )
BY BY BY BY
<descr type="string">sachin</descr> <start_t type="date">2006-10-02T01:22:15-07:00</start_t> <myArray table="myclassremit_t" elem="0"> <remit_fld type="string">one1</remit_fld> </myArray> <myArray table="myclass_remit_t" elem="1"> <remit_fld type="string">two1</remit_fld> </myArray> <myArray table="myclassremit_t" elem="2"> <remit_fld type="string">three1</remit_fld> </myArray> </myArray> </NewClass>
After loading the data, the stored object looks like this:
0 0 0 0 0 0 0 1 1 1 1 2 1 2 1 2 PIN_FLD_POID PIN_FLD_CREATED_T PIN_FLD_MOD_T PIN_FLD_READ_ACCESS PIN_FLD_WRITE_ACCESS PIN_FLD_ACCOUNT_OBJ PIN_FLD_RULES PIN_FLD_RUM_ID PIN_FLD_SCENARIO_DESCR PIN_FLD_SCHEDULE_DOWNTIME_START PIN_FLD_REMIT_FLDS PIN_FLD_REMIT_FLD PIN_FLD_REMIT_FLDS PIN_FLD_REMIT_FLD PIN_FLD_REMIT_FLDS PIN_FLD_REMIT_FLD POID [0] 0.0.0.1 /myclass 43567 0 TSTAMP [0] (1083780256) 5/6/04 3:04 AM TSTAMP [0] (1083780256) 5/6/04 3:04 AM STR [0] "L" STR [0] "L" POID [0] 0.0.0.1 /account 1 1 ARRAY [0] allocated 4, used 4 INT [0] 222 STR [0] "sachin" TSTAMP [0] (1159732335) 10/2/06 4:52 AM ARRAY [0] allocated 1, used 1 STR [0] "one1" ARRAY [1] allocated 1, used 1 STR [0] "two1" ARRAY [2] allocated 1, used 1 STR [0] "three1"
The following example shows the control file used for loading the data for the new /myclass class:
myclass_t.ctl LOAD DATA APPEND INTO TABLE MYCLASS_T ( POID_DB POID_ID0 POID_TYPE
INTEGER EXTERNAL TERMINATED BY ',', INTEGER EXTERNAL TERMINATED BY ',', CHAR TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"',
INTEGER EXTERNAL TERMINATED BY ',', INTEGER EXTERNAL TERMINATED BY ',', INTEGER EXTERNAL TERMINATED BY ',', CHAR TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"', CHAR TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"', INTEGER EXTERNAL TERMINATED BY ',', INTEGER EXTERNAL TERMINATED BY ',', CHAR TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"', INTEGER EXTERNAL TERMINATED BY ','
The following example shows the control file used for loading the data for the /myclass class PIN_FLD_RULES substruct:
myclass_rules_t.ctl LOAD DATA APPEND INTO TABLE MYCLASS_RULES_T ( OBJ_ID0 INTEGER EXTERNAL TERMINATED BY ',', REC_ID INTEGER EXTERNAL TERMINATED BY ',', RUM_ID INTEGER EXTERNAL TERMINATED BY ',', DESCR CHAR TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"', START_T INTEGER EXTERNAL TERMINATED BY ',' )
The following example shows the control file used for loading the data for the /myclass class PIN_FLD_REMIT_FLDS array:
myclass_remit_t.ctl LOAD DATA APPEND INTO TABLE MYCLASS_REMIT_T ( OBJ_ID0 INTEGER EXTERNAL TERMINATED BY ',', REC_ID INTEGER EXTERNAL TERMINATED BY ',', REC_ID2 INTEGER EXTERNAL TERMINATED BY ',', REMIT_FLD CHAR TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' )
Parent account: The following attributes should exist for the parent account:
<ActSbsc id="0.0.0.1-10001" isParent="Y">
Set id to the unique string by which the account will be identified. Set isParent to Y.
Paying child: The following attributes should exist for the paying child account:
<ActSbsc id="0.0.0.1-10002" parenRef="0.0.0.1-10001">
Set id to the unique string by which the account will be identified. Set parenRef to be a reference to its parent ID.
Non-paying child: The following attributes should exist for the non-paying child account:
<ActSbsc id="0.0.0.1-10003" parenRef="0.0.0.1-10002" payParenRef="0.0.0.1-10002">
Set id to the unique string by which the account will be identified. Set parenRef and payParenRef to be references to the parent ID and paying parent ID, respectively. The pay_type (PTyp) attribute under billinfo should be set to NPC as follows:
<ABinfo global="true"> <ACDom>26</ACDom> <ANxt>2004-07-26T01:22:15-07:00</ANxt> <BlWn>1</BlWn> <BlSgmnt>RC</BlSgmnt> <PTyp>NPC</PTyp> </ABinfo>
The payinfo_obj_type attribute under payinfo should be set to /payinfo. Also, comment out the payinfo section as follows:
<APinfo id="10004" type="/payinfo"> <DDom>26</DDom> <RelDue>2004-05-26T01:22:15-07:00</RelDue> <!-- payInvExtn> <Add>340/C Baker Street</Add> <Cty>Houston</Cty> <Cntr>USA</Cntr> <Nm>52345</Nm> <Stt>Texas</Stt> <Zip>56009</Zip> </payInvExtn --> </APinfo>
25
25
"Understanding Conversion Manager" "Mapping Legacy Data to the BRM Data Schema"
For information about performance tuning, see "Improving Conversion Manager Performance".
Important:
Conversion Manager is an optional component, not part of base BRM, and requires a separate license.
Importing Data
You import legacy data into the BRM database one file at a time.
Important:
To specify a database connection, edit the pin_cmt utility Infranet.properties file in BRM_Home/apps/cmt. BRM_Home is the directory in which you installed the BRM software.
To import data that is not stored in a new class, run the pin_cmt utility using the following syntax:
pin_cmt -import -file XML_input_data_file stage_ID
For example:
pin_cmt -import -file data.xml 100
Important:
If you have a multidatabase system, make sure the stage IDs are larger than the database IDs. For example, if you have a database with the number 0.0.0.5, use stage IDs larger than 5.
To import data that is stored in a new class, run the pin_cmt utility using the following syntax:
pin_cmt -import_custom -file XML_input_data_file stage_ID
For example:
pin_cmt -import_custom -file data.xml 100
On all parser errors, Conversion Manager rejects the whole file. Take corrective action based on the errors logged in cmt.pinlog and resubmit the corrected file. A record is rejected and not imported if its reference object is not found. For example, in case of importing a child account when the parent account is not found, the child record is rejected. The error is noted in the log file. I/O errors, such as the inability to find or open the specified document. The whole file is rejected and an error is logged. You run out of database space. Use pin_cmt with the -recover parameter to recover your data. For more information, see "Reloading Data".
To specify a database connection, edit the pin_cmt utility Infranet.properties file in BRM_Home/apps/cmt.
To deploy your converted data, run pin_cmt using the following syntax:
pin_cmt -deploy DOM stage_ID
where:
DOM is the billing cycles day of month. stage_ID is the identity of the staging area.
Reloading Data
If pin_cmt runs out of space in your BRM database for data rows, the importing process stops. Data that was not imported can be imported after more space is made available in the database.
Important:
To specify a database connection, edit the pin_cmt utility Infranet.properties file in BRM_Home/apps/cmt.
Add space to the database. Read the log files in BRM_Home/apps/cmt to find the following information:
The batch ID for the import process that did not complete.
3.
At the beginning of every control file, replace the string LOAD_DATA with CONTINUE_LOAD_DATA. In each tables control file, specify the number of records to skip for that table by using the INTO TABLE clause. For example:
INTO TABLE account_t SKIP 756
BAD_INFRANET_CONNECTION
BRM is not running The CM connection information in the pin_cmt utility Infranet.properties file is incorrect.
The input XML file is missing from the location specified in the command line. The input XML file is either not well-formed or not valid with respect to CMT XSD. The input XML file includes an incorrect parent (/group/billing) reference. The input XML file includes an incorrect paying parent (/group/billing) reference.
Table 251 (Cont.) Common pin_cmt Messages Error message INCORRECT_DEVICE_REF INCORRECT_SUB_OBJ_SERVICE_ REF INCORRECT_GSC_PARENT_REF INCORRECT_GSD_PARENT_REF INCORRECT_GSP_PARENT_REF PROCESS_IS_RUNNING SQL_ERROR Description The input XML file includes an incorrect device reference. The input XML file includes an incorrect subscription service reference. The input XML file includes an incorrect group sharing charges reference. The input XML file includes an incorrect group sharing discounts reference. The input XML file includes an incorrect group sharing profiles reference. The input XML file is either already loaded or currently being loaded by another pin_cmt instance. Internal pin_cmt error.
The testnap utility and Object Browser. See "Using testnap and Object Browser to Validate the Database". Customer Center. See "Using Customer Center to Validate Data". SQL. See "Using SQL to Validate Data".
Tip: Before performing the initial test conversion, prepare a test database by using the pin_setup script, and then create a backup of the database. Then load the current price plan and create another backup. This saves time because it is easier to reload a database than create another one.
For information on how to use testnap, see "Using testnap" in BRM Developer's Guide.
Use testnap or Object Browser to display the data in the object. Examine each field to ensure the data in the field matches the input data file. Verify that all the products and services owned by this account are present. Verify that all of the balances for this account are correct.
Find the POIDs of these objects in the /account object. Use testnap or Object Browser to display the data for each of these objects. Examine each field in the object to ensure that the data contained in the field matches the data in the input data file. Ensure that these objects reference the correct /account object.
You can retrieve account data without any errors. You can update an account without any errors. You can change payment methods successfully. For example, change an account payment method from credit card to invoice and back to credit card (use the answer_s and answer_b daemons, if necessary). If parent-child billing data was converted, verify that the parent-child grouping works correctly. To check this, do the following: Change some of the existing child accounts to orphan accounts, and some of the existing orphan accounts to child accounts. Add a few arbitrary hierarchies. Move accounts to and from the parent accounts and verify that there are no errors.
Note:
BRM contains the root account, which increases the number of accounts by 1. Remember to take this into account at the time of validation.
The total number of accounts created is equal to the total number of accounts converted from your legacy system. Use the following SQL statement:
select count(*) from ACCOUNT_T
The total number of account name and address records is equal to the total number of accounts converted from your legacy system. Use the following SQL statement:
select count(*) from ACCOUNT_NAMEINFO_T
Note:
If your implementation has more than one name and address type, you need to take this into account.
The total number of bill objects is equal to the total number of accounts converted from your legacy system. This number must equal the number of records in the ACCOUNT_T table. Use the following SQL statement:
select count(*) from BILL_T
The total number of payment objects is equal to the total number of accounts converted from your legacy system. This number should equal the number of records in the ACCOUNT_T table. Use the following SQL statement:
select count(*) from PAYINFO_T
Also verify that the total records in the PAYINFO_INV_T, PAYINFO_CC_T, and PAYINFO_DD_T tables match the number of records in the ACCOUNT_T table. Use these SQL statements:
select count(*) from PAYINFO_INV_T select count(*) from PAYINFO_CC_T
The total number of /profile objects (if created) is equal to the total number of accounts converted from your legacy system: this number should equal the number of records in the ACCOUNT_T table. Use the following SQL statement:
select count(*) from PROFILE_custom_table_T
where custom_table is the implementation-unique identifier you choose; for example, company name.
The total number of subordinate (child) accounts match the number of rows in the GROUP_BILLING_MEMBERS_T table. Use the following SQL statement:
select count(*) from GROUP_BILLING_MEMBERS_T where object_type = '/account'
The total number of parent accounts match the number of rows in the GROUP_T table. Use the following SQL statement:
select count(*) from GROUP_T where poid_type= '/group/billing'
The total number of parent accounts match the number of rows in the GROUP_ PERMITTEDS_T table. Use the following SQL statement:
select count(*) from GROUP_PERMITTEDS_T where type = '/account'
26
26
Partitioning. For information, see "Partitioning database tables" in BRM System Administrator's Guide Conversion Manager. For information, see "Understanding Conversion Manager"
Create back-dated partitions for storing legacy data. See "About your Partitioning Scheme". Configure Conversion Manager to encode a creation timestamp into specified object POIDs. See "About Making Conversion Manager Partition Aware".
About Partitioning
Some BRM database tables, such as the BILL_T table, store large amounts of data, which can slow BRM search times. Dividing large tables into smaller, more manageable chunks, called partitions, makes it easier for BRM to find data because it needs to search only a single partition for data rather than an entire table. In BRM, you create table partitions that are based on dates and are divided by a specified interval: month, week, or day. For example, you could set one partition for May 1 to May 31, the subsequent one for June 1 to June 30, and so on. Objects are stored in partitions according to their creation date and time. For example, /event objects created in May 2009 could be stored in the May 2009 partition of the EVENT_T table.
26-1
About Partitioning
Back-dated table partitions for your legacy data. For example, if you are loading legacy billing and item data into BRM, create back-dated table partitions for the /bill storable class (BILL_T table) and the /item storable class (ITEM_T table). Your back-dated tables must also comply with the following restrictions. The oldest back-dated partition that you create must have a start date prior to the creation date of the oldest legacy object you are loading into BRM. For example, if the oldest object that you are loading has a creation date of March 8, 2005, you must create a back-dated table partition that starts on or before March 7, 2005. The most recent back-dated partition that you create must have an end date that is at least one day prior to the BRM installation date. For example, if you install BRM on August 15, 2009, the most recent back-dated partition must end on or before August 14, 2009.
Future-dated partitions for data created on your new BRM system. Create future-dated partitions for any storable classes you would like partitioned. The first future-dated partition must start two days after the BRM installation date. For example, if you install BRM on August 15, 2009, the first partitions start date must be August 17, 2009 or later.
For example, assume you install BRM on August 15, 2009 and the oldest billing object in your legacy system has a creation date of January 20, 2009. In this example, you would create seven back-dated partitions and one or more future-dated partitions for your /bill storable class (BILL_T table) as shown in Table 261:
Table 261 Partition 1 2 3 4 5 6 7 8 9 10 Partioning Scheme Example Date range for each BILL_T partition January 15, 2009 February 14, 2009 February 15, 2009 March 14, 2009 March 15, 2009 April 14, 2009 April 15, 2009 May 14, 2009 May 15, 2009 June 14, 2009 June 15, 2009 July 14, 2009 July 15, 2009 August 14, 2009 August 17, 2009 September 16, 2009 September 17, 2009 October 16, 2009 partition_last
Objects with creation timestamps prior to February 15, 2009 would be automatically loaded into Partition 1. Objects with creation timestamps on or after February 15, 2009 and prior to March 15, 2009 would be loaded into Partition 2. Objects with creation timestamps after August 14, 2009 and prior to August 17, 2009 would be loaded into Partition 8.
Note:
If an objects creation timestamp is not covered by one of the partition ranges, the object is automatically loaded into the next higher-range partition.
Objects with creation timestamps after October 16, 2009 would be loaded into partition 10 (partition_last).
Note:
If an objects creation timestamp is not covered by one of the partition ranges and a higher-range partition does not exist, the object is automatically loaded into partition_last.
The creation timestamp passed in by the legacy system. In this case, you must pass the object creation timestamp in the CrtT element of the input XML file. The system time when you run Conversion Manager. It does not use the timestamp from pin_virtual_time.
You must make sure that the creation time is applied consistently to all related objects. For example:
When you migrate unpaid bills and open items from your legacy billing system to BRM, the bill objects and their associated item objects must all use the legacy objects creation time. Otherwise, the billing and invoicing utilities will not find all items associated with a bill. When you migrate balances from your legacy system to BRM, the account objects and their associated balances must all use the legacy objects creation time.
Determines which storable classes are partitioned and purgeable by reading the BRM data dictionary. In the data dictionary, partitioned and purgeable storable classes have their IS_PARTITIONED field set to 1 and their PARTITION_MODE field set to Finite. Reserves a set of POIDs for each partitioned, purgeable storable class and a single set of POIDS for all non-partitioned storable classes. For example, if the /bill and /item storable classes are partitioned and purgeable, Conversion Manager reserves three sets of POIDs: one set for /bill objects, one set for /item objects, and one set for objects of all non-partitioned storable classes. Assigns POIDs to objects based on the storable class type:
Migrating Legacy Data into BRM Table Partitions 26-3
If the storable class is partitioned and purgeable, Conversion Manager assigns a POID from the storable classs reserve of partitioned POIDs and encodes the timestamp. It uses either the timestamp passed in from the legacy system or the system time when you ran Conversion Manager. If the storable class is not partitioned, Conversion Manager assigns a POID from the reserve of non-partitioned POIDs.
Note:
If the set of reserved POIDs is already depleted, Conversion Manager reserves a new set of POIDs before assigning one to an object.
The object is then loaded into a partition according to the storable class type and the timestamp encoded in the object POID. During the loading phase, if no corresponding partition is available for the timestamp encoded in the object POID, Oracle loads the object into the next higher-range partition. If no higher-range partition is available, Oracle loads the object into partition_last. If a storable class is not partitioned, Oracle loads the object directly into the target database table.
The number of POIDs to reserve at a time. Which timestamp to encode into POIDs.
Make sure partitioning is enabled in your BRM system by performing one of the following tasks:
When installing BRM, choose to partition your database tables. After installing BRM, upgrade your non-partitioned database to a partitioned database.
For information, see "Partitioning database tables" in BRM System Administrator's Guide.
2.
Determine the oldest object for each storable class that will be partitioned in the BRM database. The oldest partitions start date must be prior to the oldest objects creation date for that storable class. Create partitions with the partition_utils utility. See "Creating Partitions for Your Legacy Data". Configure Conversion Manager for partitioning. See "Configuring Conversion Manager for Partitioning".
3. 4.
5.
Include the legacy objects creation timestamp in the Conversion Manager input XML file. See "Passing Object Creation Timestamps in the Input XML File".
where:
start_date specifies the starting date for the first partition. The format is MMDDYYYY. The oldest partitions start date must occur prior to the oldest objects creation date. quantity specifies the number of partitions to add. storable_class specifies the storable class to store in the partition. The default is /event. width specifies the number of units in a partition; for example, 3.
You must also create future-dated partitions for objects generated by your new BRM system. For information on how to create future-dated partitions, see "Partitioning database tables" in BRM System Administrator's Guide.
Open the BRM_Home/apps/CMT/Infranet.properties file in a text editor. BRM_ Home is the directory in which you installed the BRM software. Set the entries for creating partitioning-aware object POIDs:
Use infranet.cmt.timestampvalidation to specify which timestamp to encode in generated POIDs. See "Configuring which Timestamp to Encode". Use infranet.cmt.noofrecords to specify the number of POIDs to reserve for partitioned POIDs. See "Configuring the Number of POIDs to Reserve".
3.
If you specify to use the system time, Conversion Manager loads all of the legacy data into one partition. You must configure and size the appropriate partition to store the volume of data that will be loaded into it.
26-5
You specify which timestamp to encode by using the following Infranet.properties file entry:
infranet.cmt.timestampvalidation = Value
0: The timestamp is set to the creation time passed in the input XML file. If a creation time is not passed in, Conversion Manager assigns the system time when you run pin_cmt. 1: The timestamp is set to the creation time passed in the XML file only. If a creation time is not passed in, Conversion Manager generates an error. This setting ensures that all partitioned classes include the original creation timestamp. This is the default. 2: The timestamp is set to the system time when you run pin_cmt. If a creation timestamp is passed in, Conversion Manager generates an error. This ensures that all partitioned classes are loaded with the system time.
Caution!:
This parameter cannot enforce validations across multiple runs of Conversion Manager. Loading some objects with the system time and other objects with the object creation time could cause system inconsistencies and business operations to fail.
where Number is an integer that specifies the number of POIDs to reserve. The default is 1. Conversion Manager reserves the specified number of POIDs for each storable class that is partitioned.
where: Number is an integer that specifies the number of POIDs to reserve. The default is 1. Services is an integer that specifies the average number of services in your accounts. The default is 5. Devices is an integer that specifies the average number of devices in your accounts. The default is 2.
Conversion Manager multiplies these three values (Number * Services * Devices) to compute the total number of POIDs to reserve for non-partitioned storable classes.
For example, assume you partition the /bill and /item storable classes and the Infranet.properties file includes the following entries:
infranet.cmt.noofrecords = 1000 infranet.cmt.avgnoofservices = 5 infranet.cmt.avgvoofdevices = 3
1,000 POIDs for /bill objects. 1,000 POIDs for /item objects. 15,000 POIDs for all other objects.
The object creation timestamp is correct. Conversion Manager does not perform any validations on values passed in the CrtT element. Objects using the legacy creation time are not combined in the same partitioned, purgeable table as objects using the system time.
26-7
Part IV
Part IV
Part IV provides reference information about customer management utilities. It contains the following chapters:
27
27
This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) Conversion Manager utilities.
cmt_mta_cycle_fees
cmt_mta_cycle_fees
Important: The cmt_mta_cycle_fees utility is run internally by the pin_cmt utility. Do not run this utility by itself.
The cmt_mta_cycle_fees utility applies cycle forward fees to BRM accounts that have been deployed by the pin_cmt utility. See "Understanding Conversion Manager" and "Loading Legacy Data into the BRM Database".
Important:
Note:
To connect to the BRM database, the cmt_mta_cycle_fees utility needs a configuration file in the directory from which you run the utility.
Location
BRM_Home/apps/cmt where, BRM_Home is the directory in which you installed the BRM software.
Syntax
cmt_mta_cycle_fees -stage_id stage_ID -cycle_dom day_of_month
Parameters
-stage_id stage_ID
The billing day of month for the accounts that need cycle fees applied.
Results
The cmt_mta_cycle_fees utility notifies you when it runs successfully. Otherwise, look in the pin_mta.pinlog file in BRM_Home/apps/cmt for errors.
pin_cmt
pin_cmt
Use the pin_cmt utility to load legacy data in XML format into your BRM database. See "Understanding Conversion Manager" and "Loading Legacy Data into the BRM Database".
Important:
Note:
Location
BRM_Home/apps/cmt
Syntax
pin_cmt -import -file XML_input_data_file stage_ID| -import_custom -file XML_input_data_file stage_ID| -recovery load batch_ID| -deploy DOM stage_ID
Parameters
-import -file XML_input_data_file stage_ID
Ensure that there are no extra spaces in the input XML file. If you need to indent text in the XML file, use the TAB key to add space.
Imports data that uses new storable classes into the BRM database.
-recovery load batch_id
Reloads data after a failed load process. The batch ID is recorded in the cmt.pinlog file in BRM_Home/apps/cmt.
-deploy DOM stage_ID
Deploys data. DOM is the billing cycles day of the month. stage_ID is the stage ID used when the data was imported. In this example, accounts with a billing day of month of 15 and stage ID of 100 are deployed:
pin_cmt -deploy 15 100
pin_cmt
Results
The pin_cmt utility notifies you when it runs successfully. Otherwise, look in the cmt.pinlog file in BRM_Home/apps/cmt for errors. In addition, look for errors in the log file specified in the pin.conf file for the cmt_mta_cycle_fees utility.
28
28
This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) customer management utilities.
load_notification_event
load_notification_event
Loads notification XML file from Pipeline Manager into the BRM database. This allows BRM to notify customers when their balance has reached a threshold value during the batch rating process. For more information, see "About Credit Limit and Threshold Checking during Batch Rating". You must configure the Batch Controller to execute this utility. See "Configuring Batch Controller to Run load_notification_event".
Note:
To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin where, BRM_Home is the directory in which you installed the BRM software.
Syntax
load_notification_event [-d] [-v] [-h] XML_file
Parameters
-d
Sets the log level to debug and outputs debug information into the log file for this process. If not set, only error-level information is output.
-v
The name and location of the XML file to load into the BRM database. This must be the last parameter listed on the command line.
Results
This utility notifies you when it successfully loads the XML file. If the utility does not notify you that it was successful, look in the utility log file (default.pinlog) to find any errors. The log file is either in the directory from which the utility was started or in a directory specified in the configuration file.
load_pin_business_profile
load_pin_business_profile
Use this utility to load business profiles and validation templates into the BRM database. You enter this information in the business profile configuration file (BRM_ Home/sys/data/config/pin_business_profile.xml). For more information, see the following topics:
About Business Profiles Setting Up Business Profiles and Validation Templates Editing the Business Profile Configuration File
Note:
Important:
To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. For information about creating configuration files for BRM utilities, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin
Syntax
load_pin_business_profile [-d] [-h] [-r] [-t] [-v] filename
Parameters
-d
Creates a log file for debugging purposes. Use this parameter for debugging when the utility seemed to run without error but the data was not loaded into the database.
-h
Retrieves the business profile and validation template data from the BRM database and saves it in an XML file.
-t
Runs the utility in test mode to validate the XML file against its schema definition (see "Validating Your Business Profile Configuration File Edits"). This option does not create, modify, or delete any business profile or validation template objects in your BRM database.
Tip: To avoid load errors based on XML content problems, run the utility with this option before loading data into the database.
load_pin_business_profile
-v
Note:
This parameter is always used in conjunction with other parameters and commands. It is not position dependent. For example, you can enter -v at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file: load_pin_business_profile other_parameters v > filename.log
filename
The name and location of the business profile configuration file. The default file is BRM_Home/sys/data/config/pin_business_profile.xml, but the utility can take any XML file name as a parameter as long as the files contents conform to the appropriate schema definition. See "Validating Your Business Profile Configuration File Edits". If you copy filename to the same directory from which you run the load utility, specify only the file name. If you run the command in a different directory from where filename is located, you must include the entire path for the file. In addition, filename must be in the same directory as the default BRM_ Home/sys/data/config/business_configuration.xsd file.
Results
This utility notifies you only if it encounters errors. Look in the default.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file. To verify that the business profile and validation template information was loaded, display the /config/business_profile and /config/template subclass objects by using one of the following features:
For information about reading an object and writing its contents to a file, see "Reading an Object and Writing its Contents to a File" in BRM Developer's Guide.
Important:
You must stop and restart the Connection Manager (CM) to make new business profile and validation template data available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
load_pin_customer_segment
load_pin_customer_segment
Use this utility to load your customer segment definitions into the BRM database. You define customer segments in the BRM_Home/sys/data/config/pin_customer_ segment.xml file. For information about customer segments, see "Creating and Managing Customer Segments".
Note:
You cannot load separate /config/customer_segment objects for each brand. All brands use the same object.
Caution!: When you run the load_pin_customer_segment utility, it overwrites the existing customer segments in the database. If you are updating your customer segments, you cannot load new segments only. You must load complete sets of customer segments each time you run the load_pin_customer_segment utility.
Important:
To connect to the BRM database, the load_pin_customer_ segment utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin
Syntax
load_pin_customer_segment [-t] [-v] [-d] [-h] pin_customer_segment_file
Parameters
-t
Runs the utility in test mode to validate the XML file format against the XSD file, and does not load the data or overwrite any existing data. Use this option before loading data into the /config object.
-v
Note:
This parameter is always used in conjunction with other parameters and commands. It is not position dependent. For example, you can enter -v at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file: load_pin_customer_segment other_parameters v > filename.log
load_pin_customer_segment
-d
Creates a log file for debugging purposes. Use this parameter for debugging when the utility appears to have run with no errors, but the data has not been loaded into the database.
-h
The name and location of the XML file that stores localized strings for customer segments. The XML file is referenced by the pin_business_configuration.xsd file; therefore these files must be located in the same directory. The default customer segment file is in BRM_Home/sys/data/config. If you copy the pin_customer_segment.xml file and the pin_business_ configuration.xsd file to the same directory from which you run the load_pin_ customer_segment utility, you do not have to specify either the path or the file name. If you run the command in a different directory from where the pin_customer_ segment.xml file is located, you must include the entire path for the file.
Results
The load_pin_customer_segment utility notifies you when it successfully creates the /config/customer_segment object. If the load_pin_customer_segment utility does not notify you that it was successful, look in the utility log file (default.pinlog) to find any errors. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file. To verify that the customer segments were loaded, you can display the /config/customer_segment object by using the Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Writing its Contents to a File" in BRM Developer's Guide.
Important:
You must restart the Connection Manager to start recording your customer login failure preferences. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
load_pin_notify
load_pin_notify
Use this utility to add an event notification list to your BRM database. See "Loading the Event Notification List" in BRM Developer's Guide. For general information about event notification, see "Using Event Notification" in BRM Developer's Guide.
Note: You cannot load separate /config/notify objects for each brand. All brands use the same object.
Caution!:
If your database already contains an event notification list when you run this utility, the utility replaces the list in the database with the list in the configuration file that you load. If you use event notification for multiple features, you must merge the old list with the new list before running this utility. Otherwise, you will lose existing event notification functionality. See "Merging Event Notification Lists" in BRM Developer's Guide.
Important:
To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin
Syntax
load_pin_notify [-d] [-v] [-h] pin_notify_file
Parameters
-d
Specifies debug mode. The utility logs messages to the default.pinlog file in the current directory or in a directory specified in the utility configuration file. Use this parameter for troubleshooting when the utility runs with no errors but the notification file is not loaded into the database.
-v
load_pin_notify
Note:
This parameter is always used in conjunction with other parameters and commands. It is not position dependent. For example, you can enter -v at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file: load_pin_notify other_parameters v > filename.log
-h
The name and location of the configuration file that contains the event notification list you want to load into your database. The default event notification configuration file, pin_notify, is in BRM_Home/sys/data/config. For more information, see "Merging Event Notification Lists" in BRM Developer's Guide.
Tip: If you copy the pin_notify_file to the same directory from which you run load_pin_notify, you do not have to specify the path or the file name.
Results
This utility notifies you when it successfully creates the /config/notify storable object. If the utility does not notify you that it was successful, look in the utility log file (default.pinlog) to find any errors. The log file is either in the directory from which the utility was started or in a directory specified in the configuration file.
Important:
You must restart the Connection Manager to make new events and the corresponding opcodes available. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
load_pin_verify
load_pin_verify
Use this utility to load your preferences for recording customer login failures into the BRM database. You define preferences for recording customer login failures in the BRM_Home/sys/data/config/pin_verify file. For information about monitoring customer login failures, see "Tracking Customer Authentication and Authorization Records".
Note: You cannot load separate /config/verify objects for each brand. All brands use the same object.
Caution!:
When you run this utility, it overwrites the existing preferences for recording customer login failures. If you are updating your preferences, you cannot load new preferences only. You must load complete sets of preferences each time you run the utility.
Important:
To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin
Syntax
load_pin_verify pin_verify_file
Parameters
pin_verify_file
The name and location of the file that contains preferences for recording login failures. The default pin_verify file is in BRM_Home/sys/data/config.
Tip:
If you copy the edited pin_verify file to the same directory from which you run the load_pin_verify utility, you do not have to specify the path or the file name.
Results
The load_pin_verify utility notifies you when it successfully creates the /config/verify object. If the load_pin_verify utility does not notify you that it was successful, look in the utility log file (default.pinlog) to find any errors. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.
load_pin_verify
Important:
You must restart the Connection Manager to start recording your customer login failure preferences. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
load_transition_type
load_transition_type
Use this utility to load custom deal and plan transition types into the BRM database. You define custom transition types in the BRM_Home/sys/data/pricing/example/pin_ transition_type file. For information, see "Creating Custom Transition Types for Deals and Plans".
Note: You cannot load separate /config/transition_type objects for each brand. All brands use the same object.
Caution!:
When you run load_transition_type, it overwrites the existing /config/transition_type object. If you are updating your transition types, you cannot load new transition types only. You must load complete sets of transition types each time you run the utility.
Important:
To connect to the BRM database, this utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin
Syntax
load_transition_type [-v] [-d] [TransitionTypeFile]
Parameters
-v
Creates a log file for debugging purposes. Use this parameter for debugging when the utility appears to have run with no errors, but the data has not been loaded into the database.
TransitionTypeFile
The name and location of the file that contains your custom transition types. By default, the utility uses pin_transition_type. If you run the command in a different directory from where the pin_transition_type file is located, you must include the entire path for the file.
Results
This utility notifies you only if it encounters errors. Look in the default.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file.
load_transition_type
To verify that the transition types were loaded, you can display the /config/transition_ type object by using Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Writing its Contents to a File" in BRM Developer's Guide.
pin_product_clear
pin_product_clear
Use this utility to purge the Audit Accounts Product table of data that is older than a specified time period. When you modify a product in Customer Center, BRM records the details of the product modifications in the AUDIT_ACCOUTNTS_PRODUCT_T table. BRM stores audit data when a customer purchases an item product and modifies or cancels an existing subscription product.
Note:
To connect to the BRM database, the pin_product_clear utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin The pin.conf file for this utility is located in BRM_Home/apps/pinapps/pin_rerate. Run pin_product_clear from this directory.
Syntax
pin_product_clear -n days -d mm/dd/yyyy [-verbose] [test] [-help]
Parameters
-n days
Deletes all the records from the Audit Accounts Product table that are older than the number of days specified by days.
-d mm/dd/yyyy
Deletes all records from the Audit Account Product table that are dated prior to the midnight of the date you have specified.
-verbose
Note:
This parameter is always used in conjunction with other parameters and commands. It is not position dependent. For example, you can enter -verbose at the beginning or end of a command to initiate the verbose parameter. To redirect the output to a log file, use the following syntax with the verbose parameter. Replace filename.log with the name of the log file: pin_product_clear other_parameters v > filename.log
-test
Tests the utility, but does not affect the Audit Accounts Product table.
-help
pin_product_clear
Results
If the pin_product_clear utility doesn't notify you that it was successful, look in the utility log file (pin_product_clear.pinlog) to find any errors. The log file is either in the directory from which the utility was started, or in a directory specified in the configuration file.
pin_state_change
pin_state_change
Use this utility to perform bulk service state transitions based on the state expiration time (PIN_FLD_SERVICE_STATE_EXPIRATION_T field) in /service objects. A system administrator schedules the utility to run at a specified time each day. The utility finds services whose state expires on the current date and changes their state based on the applicable state transition.
Important: If you use custom service life cycles, Oracle recommends that you run the utility daily.
In the /config/lifecycle_states object associated with a service, the default next state is the state in the PIN_FLD_TRANSITIONS array whose PIN_FLD_DEFAULT_FLAG field is set to 1. If this flag is not set to 1 in any of the transitions configured for a state, this utility does not change the services state. To get the applicable state transition, this utility calls the PCM_OP_CUST_GET_ LIFECYCLE_STATES opcode. To perform the state transition, this utility calls the PCM_OP_CUST_UPDATE_ SERVICES opcode. See "Managing Service Life Cycles" for more information about changing states in custom service life cycles.
Note:
To connect to the BRM database, this utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Location
BRM_Home/bin The configuration file for this utility is located in the BRM_Home/apps/pin_state_ change directory. Run pin_state_change from that directory.
Syntax
pin_state_change [-help] [-state] [-service] [-verbose]
Parameters
-help
Performs state transitions for services in this state only. Use the name of a state defined in the <NAME> element in a config_lifecycle_states.xml file.
-service
Performs state transitions for this service type only. Use the name of a BRM service type (/service/*) that uses a custom life cycle.
pin_state_change
-verbose
Results
The log file specified in the utilitys configuration (pin.conf) file records the following:
The number of services for which this utility called the PCM_OP_CUST_ UPDATE_SERVICES opcode to make a state change The number of state changes that were successful
For information about why any failures occurred, see the log for PCM_OP_CUST_ UPDATE_SERVICES.
pin_unlock_service
pin_unlock_service
Use this utility to unlock a locked CSR account. This utility also resets the CSR account password to a temporary one. The system administrator needs to provide the temporary password while unlocking the locked CSR account. For more information, see "Unlocking a Locked CSR Account" in BRM System Administrator's Guide.
Important:
The pin_unlock_service utility needs a configuration (pin.conf) file in the same directory from which you run the utility. The pin.conf file required for running this utility is located in the BRM_Home/apps/pin_unlock_service directory. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide. Make sure that the account in the pin.conf file is not locked.
Location
BRM_Home/bin
Syntax
pin_unlock_service
Parameters
This utility accepts parameters through command prompts only. After each entry, press the Enter key to confirm your selection. For more information, see "Unlocking a Locked CSR Account" in BRM System Administrator's Guide.
Results
This utility notifies you of all the results in the command console. Look in the pin_ unlock_service.pinlog file for errors. This file is either in the directory from which the utility was started or in a directory specified in the utility configuration file.
pin_unlock_service