This chapter provides general information on how to upgrade your existing system to the latest Oracle Communications Billing and Revenue Management (BRM) release.
In this document, the BRM release running on your production system is called the old release. The release you are upgrading to is called the new release. For example, if you are upgrading from BRM 7.4 to BRM 7.5, BRM 7.4 is the old release, and BRM 7.5 is the new release.
Upgrading to a new release is a four-part process:
Plan the upgrade process.
Implement and test the upgrade on a test system.
Prepare to upgrade your production system.
Implement and test the upgrade on the production system.
The upgrade process includes these tasks:
Install BRM 7.5 (without installing the database schema).
Update the BRM database. The new BRM release includes an updated database schema with new tables and indexes. You use upgrade scripts to update your BRM database to the new schema.
Update the Pipeline Manager database. The new release includes an updated database schema with new tables and indexes. You use upgrade scripts to update your Pipeline Manager database to the new schema.
Source code for policy opcodes can change in a new release. You must merge your old release customizations into the new policy source code and recompile the policy Foams.
To support new functionality, the new software includes new configuration files. You must update those files to include the customizations made to your old system.
Other customizations in your system; such as customized invoicing, reports, general ledger reporting, and client applications; might need to be updated to work with the new BRM software.
Implement new features. You can implement new BRM functionality to improve your BRM system. See the information about new features in BRM Release Notes.
The basic steps for upgrading are:
Back up files.
Turn off service authentication and authorization.
Shut down the old release.
Back up your the old release's database.
Install BRM 7.5 (without installing the database schema).
Upgrade the BRM database schema.
Upgrade the Pipeline Manager database schema.
Install BRM 7.5 client applications and optional components.
Restore service authentication.
Note:There are additional steps if you use a multidatabase system, and optional steps for loading data.
Whether you can maintain access to the BRM system during the upgrade process:
Upgrading from BRM 7.4 to BRM 7.5
Upgrading from earlier versions to BRM 7.4
Important:You cannot provide access to your BRM system while the upgrade is in progress.
This temporary stoppage of service is because of the following reasons:
BRM 7.5 does not support AAA Gateway Manager. It requires a migration to Oracle Communications Service Broker (OCSB) Online Mediation Controller.
Note:Support for RADIUS Manager is added in BRM 7.5 Patch Set 9.
The migration process between the two systems does not permit any actions in the system being upgraded.
See Oracle Communications Online Charging Solution document for details on the migration process.
When you upgrade your production system, you must shut down BRM. This typically means that BRM cannot perform authentication and accounts cannot be created.
To minimize service outage while you upgrade, follow these tips:
Upgrade the database during off-peak hours, and do a phased upgrade. Switch authentication to promiscuous mode. See BRM RADIUS Manager located in the Oracle Communications Billing and Revenue Management (BRM) 7.4 Documentation.
Use custom applications to support authentication for services other than dialup services.
Use a custom application to register customers over the Web and to store registered accounts, which can be loaded into BRM after the upgrade.
Direct upgrades are performed with a single set of upgrade scripts. This set directly transforms the old database into the new BRM database. BRM 7.5 includes one direct upgrade script, which is from BRM 7.4 to BRM 7.5.
Incremental upgrades involve multiple sets of upgrade scripts. If you are upgrading to BRM 7.5 from any release earlier than BRM 7.4, you must perform an incremental upgrade. That is, you must first upgrade your database to BRM 7.4, and then upgrade from BRM 7.4 to BRM 7.5. For example, to upgrade from BRM 7.3 to BRM 7.5, you first run a set of scripts to upgrade the BRM database from 7.3 to 7.4, and then you run another upgrade script to upgrade the database from BRM 7.4 to BRM 7.5. In this case, Release 7.4 is called the interim release.
To perform an incremental upgrade to BRM 7.5:
Install the BRM 7.4 server software.
Run the upgrade scripts to upgrade your database from the previous release to BRM 7.4.
Run the BRM 7.4 pin_setup scripts.
Install BRM 7.5 (without installing the database schema).
Run the upgrade script to upgrade your database from BRM 7.4 to BRM 7.5.
Important:You perform other upgrade tasks, such as updating policy source code, only in the new release.
To plan your upgrade, you can perform the following tasks:
Your upgrade team should include the following team members:
A database administrator to manage the database upgrade and tune the database.
A system administrator to manage the hardware and system architecture.
A business analyst to make business decisions about changes to your BRM implementation.
A customer service representative (CSR) supervisor to assess the impact on CSRs and to train CSRs on new client applications.
You should identify who might be affected by the upgrade. For example:
You might need to give your customers advance notice of any system downtime.
If your branded service providers use BRM client applications, you should provide training to support new features. In addition, branded service providers might want to tell their customers about possible system downtime.
Tell your system administrators in advance about any changes to the system architecture.
Train CSRs on new client application functionality. If a separate staff handles customer management, they need the new client applications. In addition, if there are changes to service functionality, you can tell your CSR staff to expect more service calls than usual.
If you have any software interfaces to third-party organizations, such as a credit card processor, inform them about anything that might affect your interface.
Notify Oracle so that we can help you anticipate and avoid problems. Technical support might have additional information about upgrading BRM or information specific to your implementation.
When you upgrade, you must know all the customizations you implemented in the old release. To prepare for the upgrade, find or create the following documents:
Implementation design documents. When you first implemented BRM, you should have created documents that explained your business requirements and the customizations you made to meet those requirements. These documents help you create a list of customized components. You can also compare these documents with the documentation on new BRM features to find out whether any of your customizations can now be implemented by using standard BRM functionality.
List of customized components. This should list every file created or modified for the original implementation. You need this list to know which files must be checked against the new release for changes.
Customizations might include the following:
Additional Data Managers (DMs)
Custom Facility Modules (FMs)
Custom client applications
Merging container DESC.dsc files
Updating registry files with new registry entries
Modified storable classes
Additional storable classes
Custom table indexes
Modified configuration, properties, and INI files
Custom Web pages
A gateway service that provides access to a legacy system
You might need to make changes to your current system to accommodate new functionality in the new release. For example, if the new release changes how resource rounding works, you might need to modify your price list to support the new rounding method.
See "Upgrading BRM and Pipeline Manager" for more information.
The following features are typically affected by new releases:
Price lists (rating)
Billing and invoicing
General ledger (G/L IDs)
Client applications used by CSRs
Components that integrate credit card processors and tax software
In addition, new features might include default functionality that you implemented as a customization. In that case, it is best to replace your customizations with the new feature.
When estimating the time it will take to upgrade, consider the following:
This is an important consideration because services might be suspended and authentication and authorization might be unavailable while you upgrade the database.
The best way to determine how long the database upgrade will take is to run the upgrade scripts on a test system that duplicates the data in your production system (see "Creating Test Environments"). If this is not possible, you can estimate the time by installing and reviewing the upgrade scripts and the upgrade_path_schema_diff.html file included with the upgrade scripts. This shows you which tables are affected by the upgrade. For example, adding columns to a very large EVENT_T table can take a long time.
In general, it takes longer to upgrade large databases with large tables. A large database can take from 8 to 48 hours to upgrade.
The upgrade scripts convert your old release data to the new release format. The time required to complete an upgrade is directly proportional to the size of your database. To save time, purge or archive data that is no longer required before you shut down your production system to perform the upgrade.
Because event tables consume most of the space in a database, you can significantly reduce the size of the database by purging unneeded event objects. If you cannot purge event objects, archive those that are no longer needed.
Depending on the size and complexity of your BRM implementation, the entire upgrade process can take from 2 to 8 months. If your system architecture and customization documentation is complete and up-to-date, the time is significantly shorter.
For help with your upgrade, contact Oracle.
Before upgrading, prepare your system environment:
Install the latest releases.
Install the latest BRM-supported release of your operating system and database software. Include the latest patches. If you are not running the latest supported release of Oracle, you might need to upgrade your database software before upgrading BRM. For more information, see the following:
Check disk space and memory.
Ensure that your test environments and production system include the disk space and memory required for the new BRM release. The requirements might differ from the requirements for the old release. For more information, see the following:
Tune your system.
Upgrading is faster and easier if you first tune your system for optimal performance. For assistance with estimating the hardware and storage requirements for your BRM system, contact Oracle for more information.
To test your upgrade, create the environments described in this section. You use these environments to do the following:
Compare the default behavior of the old and new releases.
Determine what customizations you made in the old release.
Test the upgrade process and its results.
You can install multiple BRM instances on a single UNIX machine. See ”Installing and Configuring Multiple Instances of BRM on One Machine” in BRM Installation Guide.
If you install BRM on multiple systems, you can save time by compressing and moving folders and files instead of running the BRM installer on each system. When you copy the files to other systems, you might need to change some configuration file values, such as port numbers, manually if you do not use the automated installer.
Your old baseline release system should run the old BRM release with the latest ServicePak but without any customizations. Use this system to do the following:
Determine what default behavior in the old release has changed in the new release by comparing the old baseline release with the "New Baseline Release".
Determine what customizations you made in the old release by comparing the old baseline release with your existing system, which this document calls the "Old Customized Release".
Your old customized release system should run the old BRM release with your customizations. This system should be identical to your current production system. To ensure that your test upgrade ("New Customized Release (Test System)") is working properly, compare the behavior of the new customized release with the old customized release.
Your new baseline release system should run the new BRM release without any customizations. Use this system to find out how the latest BRM release works.
Your new customized release (or test) system should run the new BRM release with your customizations and an upgraded BRM database. Use this system to test the following aspects of the upgrade:
The upgrade process. The procedures used to create this system should be as close as possible to the procedures used to upgrade your production system. This ensures that you test such tasks as turning authentication on and off and copying over configuration files.
For information on the standard procedure for upgrading a production system, see "Upgrading Your Production System".
Tip:To create this system, perform a test upgrade on your "Old Customized Release".
The upgrade results. To test the outcome of your upgrade process, run all tests on this system. See "Testing Your Upgraded System".
Tip:This system's database should include the same data as your "Old Customized Release" database. That way, you can run tests on the same data and compare the results
This section explains how to transfer customizations from the old release to the new release:
Tip:When you upgrade to a new BRM release, you first install the default BRM server configuration, and you then install your customized files. To ensure that you add all your customized files to the new release, create a package that includes all your customized files.
New releases often include changes to policy opcodes. If you customized your policy opcodes, you might need to re-create your customizations after you install the new BRM release:
See your internal documentation to find out what customizations were made to policy source files. If the customizations were not documented, use a diff tool to compare the source code in the "Old Baseline Release" with the source code in your "Old Customized Release". Source code is stored in the BRM_Home/source folder.
When you know what your customizations are, use a diff tool to compare your customized source code with the source code in the "New Baseline Release".
Determine whether new features implement any of your customizations or make them irrelevant.
Merge the policy source file customizations that you still need into the new release source code. As you do so, find any changes to input and output flists. It is common for fields to change or to change from required to optional (or vice versa).
Using the libraries in the new release, recompile your custom code in the new release.
Test the new source code by using the functionality that it customizes.
When you install a new BRM release, you install new configuration files, such as the Connection Manager (CM) pin.conf file. You must update these files to include the customizations you made to them in your old system. For more information, see ”Using Configuration Files to Connect and Configure Components” in BRM System Administrator's Guide.
If you added custom classes to your old release, corresponding custom tables were added to your BRM database, and corresponding custom definitions were added to your BRM data dictionary. These customizations are not modified by the database upgrade scripts.
Depending on how the new release differs from the old release, you might need to modify the old data in your custom tables to accommodate the new release. For example, a custom table might store phone numbers in the following format: 408-555-1212. Opcodes in the new release, however, might need a different format, such as 1-408-555-1212.
Important:To upgrade the old data to the new format, you should create custom SQL scripts and incorporate them into the upgrade configuration file, upgrade.cfg, before running the database upgrade scripts.
Depending on the changes introduced by the new release, you might need to modify the structure of your custom database tables. For example, you might need to add, delete, or change the size of a column. To make such changes, use either Developer Center or the pin_deploy utility after running the database upgrade scripts. Those tools will automatically update your new database schema and data dictionary.
When you run the database upgrade scripts, the scripts overwrite standard database objects. If you deleted standard objects and re-created them with nonstandard object IDs when customizing BRM, the upgrade scripts delete those objects.
To drop a standard object from the upgraded database and re-create the object with a nonstandard ID, use the testnap create 1 poid command. This command enables you to use the POID in the input file to re-create the object instead of using a value from the POID sequence.
Since BRM reports read data stored in objects, changes to the database schema often require changes to reports. Sometimes it is easier to design new reports to work with the new database schema than to update old reports, especially when there are large-scale schema changes.
For more information, see ”About BRM Reports” in BRM Reports.
Use your "New Customized Release (Test System)" to test all custom applications that call opcodes or manipulate data in the database. Changes to storable classes and opcodes in the new release might make such applications function differently.
Note:Event objects created before release 6.7 do not have a sub-balance array. You might need to take this into consideration when designing your BRM application.
Important:You must recompile your custom applications with the new BRM libraries.
To test your "New Customized Release (Test System)", perform the tests listed in "Testing Checklist". When testing, cover all aspects of the system, including CSR activity, customer logins and service usage, and billing.
Tip:Create an upgrade process document that includes a checklist of the upgrade tasks. Part of your test is to ensure that the checklist is complete because you will use it when upgrading your production system.
When you have completed all your tests without finding any errors, run all the tests again, twice. You should run through the tests twice without error before considering the test cycle complete.
If you find any problems that indicate a BRM problem, submit it to Oracle.
Important:Document all customizations you make during the upgrade. You will need to know about them the next time you upgrade.
A good way to test your upgraded BRM implementation is to run the old release and the new release in parallel. To do so, run the old system as your production system, and import all your data into the new system. You can then run billing and perform other tasks on both systems and compare the results.
When you install a new BRM release, you run upgrade scripts to update the database schema. The scripts update the database tables and fields, including the BRM database definition. The scripts modify only default BRM objects and do not affect custom objects.
You should load actual production data into the test environment to run the database upgrade scripts with your real information. If you do not have enough hardware to load the entire database, include at least some account information.
When running the upgrade scripts on your test system, look for the following:
Data errors in your current database
Custom tables and fields that are not being used
Important:If you are performing an incremental upgrade, you must run database upgrade scripts for each incremental release. For more information, see "Direct and Incremental Upgrades".
For information about BRM error messages and other problems that you encounter in your upgraded system, see the following documents:
”Reference Guide to BRM Error Codes” in BRM System Administrator's Guide
”Resolving Problems in Your BRM System” in BRM System Administrator's Guide
Upgrading BRM can expose implementation problems. While running tests, some problems you find might be caused in part by the following:
Missing data. If your initial BRM implementation included the conversion and migration of legacy data, the conversion might not have created all necessary objects or fully populated all fields. In addition, data is sometimes mistakenly deleted. The missing data might not affect the existing BRM implementation, but later versions of BRM might need it.
Undocumented customizations. If you find what appears to be an undocumented customization, compare the "Old Baseline Release" with your "Old Customized Release". If you find an undocumented customization, be sure to document it!
New functionality. BRM functionality changes between releases. These changes might enable or require you to get rid of or change some of your customizations.
For information about how new functionality affects your system, see "Upgrading BRM and Pipeline Manager".
You should have a list of tests that were performed during your initial BRM and Pipeline Manager implementation. In addition to running all those tests, you might run new tests to cover new functionality.
Important:Before running tests in a production environment, ensure that all entries for the pin_virtual_time utility were removed from configuration files. If you are running in a test environment, it is not necessary to remove entries for the pin_virtual_time utility.
These are the basic tests you should perform on your test system:
Create accounts using the client applications and your Web interface.
Run billing, including requesting and receiving payments. Check all log files and invoices after running billing.
Run the /pin_ledger_report utility on your "Old Customized Release" and your test system, and compare the results. If the database on both systems includes the same data, the results should be the same.
Note:New functionality, such as a change in how end times are computed, can produce different results.
Run all the client applications that your implementation uses.
Test your price list by committing it to the database and purchasing every plan and deal.
Test all your optional components, such as LDAP Manager and GSM Manager. See "About Maintaining Access to the BRM System during the Upgrade Process".
Test credit card processing, including a live connection to the credit card processor.
Test tax calculation.
Test Web pages.
Test all localized client applications to ensure that they correctly display and handle data in the local language.
Test all functionality that involves multiple currencies.
Run all BRM reports that you use. If possible, run the reports against the same data in your "Old Customized Release" and your test system.
Review all log files for warnings and errors. See ”About Monitoring BRM” in BRM System Administrator's Guide.
Test all interfaces to external systems.
If you plan to import usage data into the database after running the upgrade scripts, test the import process with an importing tool such as Rated Event (RE) Loader.
Develop and test a fallback plan in case you run into problems during the production system upgrade. For example, after you shut down your production system, you should create a full backup of the system in case you need to restore it.
Run Pipeline Manager. Enter the input data to the /data/in/ directory.
Run pin_rel utility to load the rated CDRs to the BRM database.
Test the Oracle database to check whether the account information from the Pipeline Manager database syncs with the BRM database.
Before you upgrade your production system, do the following:
Make a backup of the data in your production system.
Caution:Do not begin your upgrade until you have backed up your production system.
Ensure that all files required for customizing the system are available and ready to be copied to the upgraded system. This might include configuration files and Facility Modules (FMs). Test the procedure for copying these files to the upgraded system.
Be prepared to run a full integration test on your production system after the upgrade scripts have run. Prepare any test scripts and test them before shutting down BRM.
Inform anyone who needs to know about the upgrade. See "Identifying Who Is Affected by the Upgrade".
Create a checklist for the upgrade procedure. (You should have created one while testing the upgrade. See "Testing Checklist".)
Prepare a production staging system. This system includes the "New Baseline Release" with your customized files. You build this system after testing is complete. It serves as a clean system from which to copy files to your production system. To avoid resource contention, run this system on its own dedicated hardware to simulate production performance more accurately. If you have limited resources, you can use your "New Customized Release (Test System)" system as the production staging system.