1. Installation Guide
  2. Upgrading BRM
  3. Upgrading BRM and Pipeline Manager from BRM 12.0 to BRM 15.0

15 Upgrading BRM and Pipeline Manager from BRM 12.0 to BRM 15.0

Learn about the procedures required to upgrade Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

Note:

  • A direct upgrade from the BRM 7.5 release is not supported. If you are upgrading from BRM 7.5, you must upgrade your system to BRM 12.0 first.

  • For information about the BRM 12.0 releases from which you can directly upgrade to BRM 15.0, see "Supported BRM Upgrades" in BRM Compatibility Matrix.

Before performing this upgrade, see "About Upgrading from BRM 12.0 to BRM 15.0" for information on how to plan, prepare for, and test your upgrade.

About the Upgrade

To upgrade from BRM 12.0 to BRM 15.0, upgrade the following components:

  • BRM

  • BRM software Development Kit (BRM SDK)

  • Pipeline Manager

  • Pipeline Portal Development Kit (Pipeline PDK)

Tasks Involved in the Upgrade Process

This section provides a list of tasks required to upgrade from BRM 12.0 to BRM 15.0. Some tasks are optional or apply only to certain system configurations. Be sure to check whether a task is required for your system.

Caution:

When upgrading a multischema system, pay close attention to the system on which each task is performed.

Complete these tasks to upgrade your BRM system:

  1. Shut down the current instance of BRM. See "Shutting Down the Current Instance".

  2. Turn off service authentication and authorization. See "Turning Off BRM Service Authentication and Authorization".

  3. Create a complete backup of your BRM 12.0 data. See "Creating a Complete Backup of Your BRM 12.0 Data".

  4. Create a new schema in BRM 15.0. See "Creating Your BRM 15.0 Database".

  5. Import your data BRM 12.0 data. See "Importing Your BRM 12.0 Data".

  6. Install Java. See "Installing Java".

  7. Install Perl. See "Installing Perl".

  8. Obtain the ojdbc8.jar jar file. See "Downloading the ojdbc8.jar File".

  9. Set the environment variables. See "Setting the Environment Variables for Upgrade".

  10. Set the BRM wallet location in sqlnet.ora. See "Setting BRM Wallet Location in sqlnet.ora".

  11. Obtain the BRM software. See "Downloading the BRM Software".

  12. Install the upgrade package. See "Installing BRM and Pipeline Manager for Upgrade".

  13. Point your BRM 15.0 installation to the new database schema. See "Pointing the BRM 15.0 Installation to the Database Schema".

  14. Upgrade the BRM database schema to the BRM 15.0 schema. See "Upgrading the BRM Database Schema to the BRM 15.0 Schema".

  15. Upgrade the Pipeline Manager database schema to the BRM 15.0 schema. See "Upgrading the Pipeline Manager Database Schema to the BRM 15.0 Schema".

  16. Install BRM 15.0 client applications. See "Installing the BRM 15.0 Client Applications".

  17. Add optional components. See "Adding Optional Components".

  18. Check other database configurations. See "Updating Configurations".

  19. Upgrade Account Migration Manager for multischema systems. See "Upgrading AMM in a Multischema System".

  20. Restore customizations in BRM 15.0. See "Restoring Customizations".

Preparing for the Upgrade

This section describes the steps you must complete before starting the upgrade.

Shutting Down the Current Instance

Note:

On multischema systems, first perform this task on the primary system, and then on the secondary systems.

To shut down BRM 12.0:

  1. Ensure that no users are logged in.

    Users include customers, client applications, customer service representatives (CSRs), and so on.

  2. Stop all BRM 12.0 processes. For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

    Only the database instances should be running during the installation.

Turning Off BRM Service Authentication and Authorization

Note:

On multischema systems, first perform this task on the primary system, and then on the secondary systems.

To maintain a controlled environment for pre-upgrade testing, cut off interaction between your BRM system and your customers.

Creating a Complete Backup of Your BRM 12.0 Data

Creating a complete backup of the data in your BRM 12.0 environment requires the following actions to be performed in your BRM 12.0 environment:

  1. Backing Up BRM Files

  2. Backing Up Your BRM and Pipeline Manager 12.0 Databases

Backing Up BRM Files

Back up your BRM 12.0 files.

Note:

If you are performing the upgrade on systems with distributed or HA architecture, back up the files on every node.

In particular, ensure that you back up the following files:

  • All files customized for BRM 12.0 including any associated source code

  • Registry files

  • Policy files

  • pin.conf

  • pin_setup.values

  • Infranet.properties

  • All other files that contain any customizations used in BRM 12.0

Note:

Back up all customized load utility files to a different location. The data in these files is used to transfer and restore your customizations after upgrading to BRM 15.0.

For more information, see "Transferring Customizations to the New Release".

Backing Up Your BRM and Pipeline Manager 12.0 Databases

Note:

  • On multischema systems, perform this task first on the primary database schema and then on the secondary database schemas.

  • Additionally, record the system time of each backup file so that you can match that time entry to import the backup data into the appropriate system in BRM 15.0.

Make a complete offline backup of your BRM database and, if you are using Pipeline Manager, also the Pipeline Manager database. Make the backup using the appropriate backup tools for your database version and ensure that the backup is completely valid and usable. The backup must contain both the database definition and all the database contents. See your database software documentation for more information on performing full database backups.

In addition to the backup, use the Oracle export exp or expdb utility to export all BRM 12.0 tables. This helps to restore individual tables, if necessary. For more information about the exp and expdb utilities, see the discussion on export and import utilities in the appropriate version of the Oracle Database Utilities document.

Note:

Store this backup in a safe location. The data in these files will become necessary if you encounter any issues in the upgrade process.

Creating Your BRM 15.0 Database

Note:

On multischema systems, perform this task first on the primary database schema and then on the secondary database schemas.

Create a blank BRM database into which you will import the backup you created.

Upgrading to BRM 15.0

This section describes the steps necessary to upgrade to BRM 15.0.

Importing Your BRM 12.0 Data

Note:

On multischema systems, perform this task first on the primary database schema and then on the secondary database schemas.

After you have successfully created a new schema, create a BRM database user (which is the same as the database user in BRM 12.0), and then import the backup data you created in "Backing Up Your BRM and Pipeline Manager 12.0 Databases". When you import the backup data, check the system time of each backup file to ensure that the data is imported into the appropriate system in BRM 15.0.

Use the imp or impdb utility to import the backup data. For more information about the imp and impdb utilities, see the discussion on export and import utilities in the appropriate version of the Oracle Database Utilities document.

After you complete the import process, make sure that there are no invalid objects in the database schema. If there are any invalid objects, try to compile them.

Setting the Environment Variables for Upgrade

Before installing the upgrade, ensure that the environment variables are set correctly. For information about the latest compatible versions of Java, Perl, and Kafka, see "BRM Software Compatibility" in BRM Compatibility Matrix.

To set the environment variables, perform the following for all users you are going to use to install or run the BRM server:

  1. Set the JAVA_HOME environment variable to the directory in which the latest version of Java certified with BRM is installed by running the following command:

    setenv JAVA_HOME java_path

    where java_path is the path to the directory in which the latest version of Java certified with BRM is installed; for example, /Linux/x86_64/packages/jdk/jdk1.8.0_381.

  2. Verify the Java version by running the following command:

    java -version

    The Java version is displayed.

    If the latest version of Java certified with BRM is not displayed, the latest Java version is not installed in the directory specified by JAVA_HOME.

  3. Set the PERL_HOME environment variable to the directory in which the latest version of Perl certified with BRM is installed by running the following command:

    setenv PERL_HOME Perl_path

    where Perl_path is the path to the directory in which the latest version of Perl certified with BRM is installed; for example, /perl_5_38_0/linux.

  4. Set the PATH environment variable by running the following command:

    setenv PATH $JAVA_HOME/bin:$PERL_HOME/bin:${PATH}
  5. If your BRM client wallet is not stored in the default location, set the BRM_CONF_WALLET and BRM_WALLET environment variables to point to the directory in which the BRM client wallet is stored:
    setenv BRM_CONF_WALLET brm_wallet_path
setenv BRM_WALLET brm_wallet_path
  6. Set the TNS_SERVICE_NAME environment variable to the service name for your primary database:
    setenv TNS_SERVICE_NAME service_name

  7. Set the HOSTNAME environment variable by running the following command:

    setenv HOSTNAME hostName

    where hostName is the fully qualified host name of the machine on which your current instance of BRM is installed.

  8. If you will be using the Kafka Data Manager (DM), set the Kafka environment variables:

    Note:

    The Kafka DM is supported in BRM 12.0 Patch Set 4 and later releases. 
    setenv KAFKA_HOME Kafka_path
setenv KAFKA_BOOTSTRAP_SERVER_LIST KafkaHost1:port1,KafkaHost2:port2

    where:

    • Kafka_path is the path to the directory in which the Kafka library JARs are installed.
    • KafkaHost1:port1,KafkaHost2:port2 are the hosts and ports that the Kafka client will connect to in a bootstrap Kafka cluster the first time it starts. You can specify any number of hosts and ports in this list.

      You can alternatively set this list in the dm_kafka_config.xml file. See "Mapping Business Events to Kafka Topics" in BRM Developer's Guide.

Installing BRM and Pipeline Manager for Upgrade

To install BRM and Pipeline Manager for upgrade:

  1. Download the BRM software. See "Downloading the BRM Software".

  2. Go to the directory where you downloaded the BRM installer, and start the installer. See "Starting the BRM GUI Installer".

    The Welcome window appears.

  3. Click Next.

    The Installation Location window appears.

  4. Enter the full path or browse to the directory in which BRM 15.0 is going to be installed. Click Next.

    Caution:

    Install BRM 15.0 in a different location from BRM 12.0 to avoid many upgrade problems.

    The Installation Type window appears.

  5. Select Custom, and then click Next.

    The Feature Sets Selection window appears.

  6. From the components list, select Upgrade Manager Framework and then select the components that you already installed in BRM 12.0. Click Next.

    Upgrade Manager Framework contains the BRM server upgrade and the Pipeline Manager upgrade.

    Note:

    • Ensure that you select the components in Upgrade Manager Framework (Portalbase Upgrade for BRM and Pipeline Upgrade for Pipeline Manager) that correspond to the components already installed in your BRM 12.0 or BRM 12.0 patch set environment. In the rest of the list, you must also select the same components that are already installed in your BRM 12.0 or BRM 12.0 patch set environment. You can install any additional optional component after completing the BRM 15.0 upgrade. See "Adding Optional Components" for instructions on installing the optional components.

    • If the existing BRM components are installed on separate machines, install the respective 15.0 component on the machine on which the existing component is installed. For example, if the BRM server and Pipeline Manager are installed on separate machines, install the BRM 15.0 server on the machine on which the existing BRM server is installed and BRM 15.0 Pipeline Manager on the machine on which existing Pipeline Manager is installed.

    If you selected only the components in Upgrade Manager Framework, proceed to step 10.

    If you selected the components in Upgrade Manager Framework and other components from the components list, the Specify Prerequisite Libraries Location window appears.

  7. Specify the information in Table 15-1, and then click Next.

    Table 15-1 Specify Prerequisite Libraries Location

    Field Description

    Prerequisite Libraries

    Enter the full path or browse to the directory in which the prerequisite libraries are stored.

    Enable SSL for BRM server

    If you do not want to enable secure communication between BRM server components, deselect the Enable SSL for BRM server check box.

    To enable secure communication between BRM server components, leave the Enable SSL for BRM server check box selected.

    The Oracle Wallet Details window appears.

  8. Enter the information in Table 15-2, and then click Next.

    Table 15-2 Oracle Wallet Details

    Field Description

    Wallet Password

    Enter the password for the BRM 12.0 client wallet.

    Wallet Location

    For a standalone instance or a primary instance, enter the full path or browse to the directory in which the BRM client wallet for your 12.0 installation is located, for example, BRM12_home/wallet/client.

    For a secondary instance, enter the full path or browse to the directory in which the BRM client wallet or your primary instance is located, for example, BRM15_home/wallet/client.

  9. In the Specify Wallet Details window, enter the details listed in Table 15-3 and then click Next.

    Table 15-3 Specify Wallet Details

    Field Description
    Client Wallet Password

    The password for the client Oracle wallet. Use the same password used for 12.0. In a multischema system, this should be the same wallet password used in the primary schema for 12.0.
    Confirm Client Password

    This field is inactive for upgrade, since the password should be the same as the one for 12.0.
    Root Wallet Password

    The password for the root Oracle wallet
    Confirm Root Password

    The root Oracle wallet password again
    Server Wallet Password

    The password for the server Oracle wallet
    Confirm Server Password

    The server Oracle wallet password again

  10. In the following windows, provide the requested information, and then click Next, with the following considerations for upgrade:

    • In the BRM Root User Details window, in the Root Password field, ensure that you enter the existing BRM root password that you provided during the BRM 12.0 installation.

    • In the Select Running the pin_setup Script window, select Yes. This will create the appropriate pin.conf files for your 15.0 environment. Because you selected upgrade packages to install, this will not initialize the database.

    • Although it is recommended that you stop all services before running the upgrade, you can have the BRM 12.0 environment running during the installation of BRM 15.0. If this is the case, or if the two environments are ever going to be running at the same time, ensure that you provide different port numbers for the feature sets than the ones used for BRM 12.0 to avoid port conflict.

    See "Installing All BRM Components" for descriptions of the fields displayed. Continue moving through the windows until the Installation Summary window appears.

    Your responses are written to the BRM_home/setup/pin_setup.values file, where BRM_home is the directory in which the BRM 15.0 server software is installed.

  11. In the Installation Summary window, review your selections, and then click Install.

    The Installation Progress window appears, and the installation begins.

    Note:

    After the installation begins, you cannot stop or cancel the installation.

  12. When the installation is done, click Next.

    The Installation Complete window appears.

    The installer checks for all required software and displays errors if it detects any missing or unavailable components or if any connectivity issues occur.

  13. Click Finish to exit the installer.

  14. Proceed to "Upgrading Your Data to BRM 15.0".

Upgrading Your Data to BRM 15.0

This section describes the tasks to be completed to upgrade your data to BRM 15.0.

Pointing the BRM 15.0 Installation to the Database Schema

Note:

On multischema systems, first perform this task on the primary system and then on the secondary systems.

Before you run the BRM database upgrade script, verify that the Oracle Data Manager (DM) is configured correctly as this DM provides the interface to the BRM 15.0 database. The Oracle DM should point to the BRM 15.0 database in which you imported your BRM 12.0 backup data, as described in "Importing Your BRM 12.0 Data".

Verify that Oracle DM is configured properly by starting dm_oracle. You should ensure that Oracle DM starts and stops correctly because upgrade scripts start and stop Oracle DM while making changes to the database schema.

Upgrading the BRM Database Schema to the BRM 15.0 Schema

Note:

On multischema systems, first perform this task on the primary system and then on the secondary systems.

To upgrade the BRM 12.0 database schema to a BRM 15.0 database schema, complete the appropriate steps in this section.

Upgrading the Schema on Single-Schema Systems

To upgrade the BRM schema on single-schema systems:

  1. Grant additional permission to the BRM database user:
    1. Connect to the primary database instance using SQL*Plus:
      % sqlplus system@databaseAlias as sysdba
    2. Run the following command:
      SQL> GRANT SELECT ON V_$SESSION TO BRM_user;
Grant succeeded.
SQL> commit;
Commit complete.
    3. Exit SQL*Plus.

  2. Edit the BRM_home/setup/scripts/pin_setup.values file and ensure that the following values are set: 

    $SETUP_INIT_DB=YES
$SETUP_DROP_ALL_TABLES=NO
$CREATE_DATABASE_TABLES=NO

    Also set/verify the following values:

    • (Optional) Set PIN_TEMP_DIR to the directory in which you want to create the temporary files. Ensure that the directory is set with full write permissions.

    • (Optional) Set PIN_LOG_DIR to the directory in which you want to create the BRM log files.

    • Validate the other information in the file, especially the information about the database.

  3. Save and close the file.

  4. Edit the BRM_home/setup/pin_tables.values file and set the following values: 

    $PIN_CONF_PARTITION_IND             = "local";
$PIN_CONF_NON_EVENT_PARTITION_IND   = "local";

  5. Save and close the file.

  6. Run the source command on the source.me file:

    • For Bash Shell:

      source source.me.sh

    • For C shell:

      source source.me.csh

  7. Go to the BRM_home/setup/scripts directory and run the following command:

    Note:

    • Ensure that you do not run the upgrade script in the background.

    • Ensure that the WALLET_FILE_STORAGE_T table is present in the database before running this script.

    perl script

    where script is either pin_upgrade_15.pl for BRM 15.0.0 or pin_upgrade_15psx.pl for a maintenance release with x as the maintenance release, such as 1 for BRM 15.0.1, 2 for BRM 15.0.2, and so on. For example, if you are upgrading to BRM 15.0.1, run the following command: 

    perl pin_upgrade_15ps1.pl

    This script runs a series of scripts that upgrade the BRM data from BRM 12.0 to BRM 15.0.x.

    Note:

    Do not press any button until the command prompt asks for the BRM wallet password in the next step. Otherwise, the script will consider whatever key you have pressed to be the BRM wallet password.

  8. At the "Enter Password for the wallet" prompt, enter the BRM client wallet password (which should be the same for both 12.0 and 15.0) and wait for the script to finish.

  9. Merge the contents of the backed up pin_ctl.conf file into the new pin_ctl.conf file.

Upgrading the Schema on Multischema Systems

To upgrade the schema on multischema systems, you upgrade the primary database schema and then the secondary database schemas.

To upgrade the primary database schema, perform the tasks in "Upgrading the Schema on Single-Schema Systems" on your primary schema.

To upgrade each secondary database schema, perform the following on each secondary BRM installation machine:

  1. Grant an additional permission to the BRM database user:
    1. Connect to the primary database instance using SQL*Plus:
      % sqlplus system@databaseAlias as sysdba
    2. Run the following command:
      SQL> GRANT SELECT ON V_$SESSION TO BRM_user;
Grant succeeded.
SQL> commit;
Commit complete.
    3. Exit SQL*Plus.

  2. Before you upgrade the secondary schema, set the BRM_WALLET environment variable to the BRM wallet in the primary schema:

    setenv BRM_WALLET BRM_home/wallet/client

  3. Perform the tasks in "Upgrading the Schema on Single-Schema Systems" on your secondary schema.

To configure your entire multischema system, perform the following on the appropriate BRM instances:

  1. On the primary BRM instance, edit the BRM_home/apps/multi_db/config_dist.conf file and add a line specifying the schema name at the end of each block in the file. For example, if you have two database schemas, your file might look like this: 

    DB_NO = "0.0.0.1" ;        # 1st database config block.
PRIORITY = 1 ;
MAX_ACCOUNT_SIZE = 100000 ;
STATUS = "OPEN" ;

DB_NO = "0.0.0.2" ;        # 2nd database config block.
PRIORITY = 1 ;
MAX_ACCOUNT_SIZE = 100000 ;
STATUS = "OPEN" ;

    Update the file to look more like the following:

    DB_NO = "0.0.0.1" ;        # 1st database config block.
PRIORITY = 1 ;
MAX_ACCOUNT_SIZE = 100000 ;
STATUS = "OPEN" ;
SCHEMA_NAME = "pin01" ;

DB_NO = "0.0.0.2" ;        # 2nd database config block.
PRIORITY = 1 ;
MAX_ACCOUNT_SIZE = 100000 ;
STATUS = "OPEN" ;
SCHEMA_NAME = "pin02" ;

    using the correct schema names for your environment.

  2. Edit the BRM_home/setup/scripts/pin_multidb.conf file in the primary BRM instance and set the following values for each secondary database: 

    #-------------------------
# Secondary db information
#-------------------------

$PIN_MD_SECONDARY_DBNO     [0] = "db_no";
$PIN_MD_SECONDARY_OWNER    [0] = "sec_owner"; 
#$PIN_MD_SECONDARY_PASSWD  [0] = "pinb";
$PIN_MD_SECONDARY_DBNAME   [0] = "sec_db";
$PIN_MD_SECONDARY_SQLHOST  [0] = "";            
$PIN_MD_SECONDARY_HOSTNAME [0] = "sec_hostname";
$PIN_MD_SECONDARY_PORT     [0] = "dm_port";       # dm port
    where:

    • db_no is the database number of the secondary schema, for example 0.0.0.2.

    • sec_owner is the owner of the secondary database.

    • sec_db secondary database name.

    • dm_port port for the DM.

  3. Go to the BRM_home/setup/scripts directory in the primary BRM instance and run the following command: 

    pin_multidb.pl -i

    1. At the following prompt, enter y, which begins the configuration: 

      Do you want to start the configuration now? (y/n):   y

    2. At the following prompt, enter 2, which initializes the primary database: 

      Please enter the starting step (0-8). If you don't know, enter 0:   2

    3. Follow the instructions displayed and exit the pin_multidb.pl script.

      At the prompt to enter the wallet password, enter the wallet password for the primary schema.

  4. Restart the Connection Manager (CM) and DM of your primary BRM instance. Ensure that the testnap utility works.

  5. Run the following command in the primary BRM instance:

    pin_multidb.pl -f

  6. Edit the DM pin.conf file on the primary BRM instance and set the following value for each secondary schema: 

    - dm schema db_no sec_owner
    where:

    • db_no is the database number of the secondary schema, for example 0.0.0.2.

    • sec_owner is the owner of the secondary database.

  7. Edit the DM pin.conf file on each secondary BRM instance and set the following values for the primary schema: 

    - dm schema 0.0.0.1 prim_owner
    where:

    • prim_owner is the owner of the primary database.

  8. Stop and restart all of the services on the primary BRM instance and all secondary instances.

  9. On the primary BRM instance, connect to SQL*Plus and run the following scripts:

    @create_procedures_character_set.plb
grant_permissions_oracle.plb
grant_permissions('sec_owner')
    where:

    • character_set specifies the database character set, either UTF8 or AL32UTF8.

    • sec_owner is the owner of the secondary schema.

    Run the last command for the owner of each secondary schema.

  10. On each secondary BRM instance, connect to SQL*Plus and run the following scripts:

    @create_procedures_character_set.plb
grant_permissions_oracle.plb
grant_permissions('prim_owner')
    where:

    • character_set specifies the database character set, either UTF8 or AL32UTF8.

    • prim_owner is the owner of the primary schema.

  11. On the primary BRM instance, do the following for each secondary schema:

    1. Edit the BRM_home/sys/dd/data/device_framework_primary_schema_75ps4.sql script and update all instances of SEC_SCHEMA_NAME to the name of the secondary database schema owner.

    2. Connect to the primary database schema and run the edited script in SQL*Plus.

  12. On each secondary BRM instance, connect to the secondary database schema and run the BRM_home/sys/dd/data/device_framework_secondary_schema_75ps4.sql script in SQL*Plus.

Upgrading the Pipeline Manager Database Schema to the BRM 15.0 Schema

Note:

Run the database upgrade script on the primary schema and then on the secondary schemas.

To upgrade the Pipeline Manager database schema:

  1. Create a temporary directory for use during the upgrade by going to Pipeline_home/upgrade and creating the Pipeline_home/upgrade/tmp directory.

  2. Update the Pipeline_home/upgrade/pipeline_upgrade.cfg file and set the following values: 

    $PIN_TEMP_DIR = "temp_path"
$MAIN_DB{'user'} = "db_user";
$PIPELINE_TBLSPACE = "tablespace pipeline_tablespace";
    where:

    • temp_path is the directory you just created.

    • db_user is the primary database user.

    • pipeline_tablespace is the tablespace containing pipeline data.

    Ensure that you also update the database information as appropriate.

  3. Grant the required access to the user pin on the Pipeline Manager tables and sequences, if you have not already done so. See "Loading the Tailor-Made Stored Procedure" for more information about the Pipeline Manager tables and sequences that you should grant user pin access to.

  4. Go to the Pipeline_home/setup/scripts directory and run the following command:

    Note:

    • Ensure that you do not run the upgrade script in the background.

    • Ensure that the WALLET_FILE_STORAGE_T table is present in the database before running this script.

    perl script

    where script is either pin_upgrade_15.pl for BRM 15.0.0 or pin_upgrade_15psx.pl for a maintenance release with x as the maintenance release, such as 1 for BRM 15.0.1, 2 for BRM 15.0.2, and so on. For example, if you are upgrading to BRM 15.0.1, run the following command: 

    perl pin_upgrade_15ps1.pl

    This script runs a series of scripts that upgrade Pipeline Manager data from 12.0 to 15.0.x. The log files will be located in the temporary directory you created.

  5. In SQL*Plus, run the Pipeline_home/database/Oracle/Scripts/create_pricing_discountmodel_procedures.plb script in the Pipeline schema.

Completing the Upgrade

This section describes the tasks required to complete the upgrade process.

Creating Large Indexes

For performance reasons, you must create two indexes manually after the upgrade.

To create the indexes in the default tablespace, use the following commands: 

CREATE INDEX i_event_item_tr_arbill__id ON event_item_transfer_t (ar_bill_obj_id0);
CREATE INDEX i_event_session_obj__id ON event_t (session_obj_id0);

To create the indexes in another tablespace (for example, the index tablespace), use the following commands:

CREATE INDEX i_event_item_tr_arbill__id ON event_item_transfer_t (ar_bill_obj_id0) tablespace tablespace_name;
CREATE INDEX i_event_session_obj__id ON event_t (session_obj_id0) tablespace tablespace_name;

where tablespace_name is the name of the tablespace that should contain the indexes.

Installing the BRM 15.0 Client Applications

When you install client applications, be sure to update the BRM 15.0 Infranet.properties and INI files with any 15.0 customizations. See "Installing BRM Thick Clients" for more instructions.

Note:

You must upgrade all existing client applications and optional components to BRM 15.0 before you install additional client applications and optional components in BRM 15.0.

To upgrade custom client applications, recompile them with BRM 15.0 libraries. See "Updating Custom Applications" for more information.

Adding Optional Components

At this point, add the optional components that you plan to use in BRM 15.0. See "Installing Individual BRM Components" for instructions.

Note:

Before you install a new optional component, in case you changed the database password after the previous installation, ensure that the database password is the same in all configuration entries in the Oracle wallet. To change the database password in the configuration entries, see "About Oracle Wallet" in BRM System Administrator's Guide for more information.

Updating Configurations

Complete the steps in this section that are appropriate for your BRM 15.0 environment.

Update the Default Settings for the pin_rel Utility

If you use Rated Event (RE) Loader, ensure that the database configurations settings are updated.

To update the default settings for the pin_rel utility:

  1. Go to the BRM_home/apps/pin_rel directory.

  2. Open the Infranet.properties file.

  3. Check and, if necessary, update the entries for the following:

    infranet.rel.dbname = DATABASE_NAME
infranet.rel.userid = USERNAME

  4. Save and close the file.

Updating the Settings for the pin_virtual_time Utility

If you are testing the upgrade on a test system, ensure that you uncomment all entries for the pin_virtual_time utility in the configuration files associated with your BRM test system.

If you are upgrading your production system, ensure that you remove all entries for the pin_virtual_time utility from the configuration files associated with your BRM production system.

Upgrading AMM in a Multischema System

If you have a multischema system and it includes Account Migration Manager (AMM), run the AMM installation scripts to upgrade your multischema system.

To upgrade AMM in a multischema system:

  1. Log in as user pin and go to the BRM_home/setup/scripts directory.

  2. Run the pin_amt_install script: 

    perl pin_amt_install.pl

Restoring Customizations

Note:

You must first incorporate customizations on the primary schema and then on the secondary schemas.

Incorporate any customizations you made to your Release 12.0 policy source code, configuration files, invoicing, reports, and general ledger reporting. See "Transferring Customizations to the New Release" for more information.

Post-Upgrade Procedures

This section provides a list of post-upgrade tasks. Some tasks are optional or apply only to certain platforms or system configurations. Be sure to check whether a task is required for your system.

Perform these tasks after you upgrade your BRM system:

  1. Loading the pin_notify File
  2. Copying Files for Compiling CMs
  3. Migrating Custom Code to a 64-bit Environment
  4. Updating Queue Handling
  5. Setting the Environment Variables for Pipeline Manager
  6. Configuring SSL for the BRM Database
  7. Removing Invalid Objects from the Database
  8. Modifying the Root Encryption Key
  9. Setting the Bill State for Preexisting Bills
  10. Migrating Tax Codes
  11. Updating pin_inv_doc_gen Infranet.properties

Loading the pin_notify File

Note:

On multischema systems, first perform this task on the primary system and then on the secondary systems.

If your system includes Pipeline Manager, reload the event notification configuration file, pin_notify, in the BRM database. For more information, see "About the Event Notification List" in BRM Developer's Guide.

To load the pin_notify file:

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

  2. Run the following command:

    load_pin_notify pin_notify

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

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

Copying Files for Compiling CMs

You must copy some files required for building versions of the CM.

To copy the required files for compiling CMs:

  1. Copy the following files from the BRM_home/lib directory to the BRM_home/PortalDevKit/source/sys/cm directory:

    • libcmpin.so

    • libdmpin.so

  2. Copy the cm.cpp file from the BRM_home/source/sys/cm directory to the BRM_home/PortalDevKit/source/sys/cm directory.

  3. Open the BRM_home/PortalDevKit/source/samples/env.unix file in a text editor.

  4. Add or modify the following environment variables:

    LIBDIR = BRM_home/PortalDevKit/lib
RW_INCDIR = PortalDevKit_hostname/rwWorkspace
INCDIR = BRM_home/PortalDevKit/include
PCM_JAR = BRM_home/jars/pcm.jar
JDK_HOME = jdk_path
PCMEXT_JAR = BRM_home/jars/pcmext.jar

    where:

    • hostname is the name of the machine on which the BRM server is installed.

    • jdk_path is the path to the directory in which the latest version of JRE certified with BRM is installed, such as /Linux/x86_64/packages/jdk/jdk1.8.0_381.

  5. Save and close the file.

Migrating Custom Code to a 64-bit Environment

To migrate the code for your policy opcodes to 64-bit.

  1. If you are using custom makefiles, make the following changes in each:

    • If the makefile contains -m32, remove it.

    • Remove elf_i386 from the file, or replace it with elf_x86_64.

    • Update the dynamic linking path for 64-bit. For example, change -shared -L/usr/lib to -shared -L/usr/lib64

  2. Change the format specifiers for variables whose sizes are different for 64-bit. For specifics, see Table 15-4.

    Table 15-4 Changes in Data Type Format Between 32-bit and 64-bit

    Data type 32-bit Length 64-bit Length
    time_t 4 bytes 8 bytes
    Pointer 4 bytes 8 bytes
    long 4 bytes 8 bytes
    wchar_t 2 bytes 4 bytes
    size_t 4 bytes 8 bytes

    Note:

    The int and int32 data types remain 4 bytes, and the int64 data type remains 8 bytes.

  3. Make specific changes relating to time/date formats, to allow for dates beyond the year 2038.

    • If your code ever uses the int data type for a date, change the type to time_t. While the int data type remains at 4 bytes, the time_t data type has increased to 8 bytes.

    • When your code calls any PCM library function, such as PIN_FLIST_FLD_SET or PIN_FLIST_FLD_GET, use variables of type time_t or pin_fld_tstamp_t for any PIN_FLDT_TSTAMP fields.

  4. Enable the -Wconversion flag during compilation so that it will report any warnings related to implicit type conversions. Solve all of those errors. In particular, make sure you solve any Wpointer-to-int-cast warnings. These might be generated by pointers that assume the old data type sizes.

  5. Be aware of the magic numbers and any Bit Shifting Operations being used in the code. These may need to be changed. For example, some issues with magic numbers are:

    longvar = 0xffffffff; //-1 in 32-bit environment 
longvar = 0xffffffff; //4294967295 in 64-bit environment
longvar = 0xffffffffffffffff; //-1 in 64-bit environment

Updating Queue Handling

The dm_ifw_sync and dm_aq queues were previously used for Advanced Queuing in BRM. However, the Account Sync Manager (dm_ifw_sync) and the Queue Manager (dm_aq) components have been deprecated in BRM 15.0. Their functionality has been moved to dm_oracle, which has been enhanced to enqueue these messages going forward.

The BRM_home/apps/pin_ifw_sync/ and BRM_home/apps/pin_aq/ directories are not present in BRM 15.0. They have been replaced by a new directory, BRM_home/apps/pin_publish_aq/. This directory contains the pin_publish_oracle.pl utility, which is used to maintain Advanced Queues meant to publish messages for enterprise integration and the Pipeline Rating Engine.

To update your system for this change:

  1. Update the payload configuration XML files located in BRM_home/sys/eai_js to change the publisher database number. Change the numbers 0.0.9.7 (dm_aq) and 0.0.9.9 (dm_ifw_sync) to 0.0.0.0. This will route the events to dm_oracle.

  2. Update the business event queue mapping by updating the BRM_home/sys/dm_oracle/aq_event_map file with the information that was previously directed to dm_ifw_symc and dm_aq. This file is equivalent to the previous ifw_sync_queuenames file.

    The DM pin.conf file has been updated to contain the following parameter:

     - dm aq_event_map_file ./aq_event_map

    You can use this parameter to change the name of the queue file according to your requirements.

Setting the Environment Variables for Pipeline Manager

If your system includes Pipeline Manager and if you have the Oracle ZT PKI Encryption enabled in BRM 12.0, you must set some environment variables for Pipeline Manager.

On the machine on which you installed the BRM 15.0 server, set the BRM_WALLET environment variable for pipelines by running the following command:

setenv BRM_WALLET Pipeline_home/wallet/client

Configuring SSL for the BRM Database

You can configure secure sockets layer (SSL) for the BRM database by creating wallets for storing certificates and then modifying the following configuration files in the Oracle_home/network/admin directory, where Oracle_home is the directory in which the Oracle database is installed, to point to the appropriate wallet:

  • sqlnet.ora

  • tnsnames.ora

  • listener.ora

You can use the Orapki utility to create the wallets.

For information about configuring SSL for the Oracle database, see the Oracle Database documentation.

Removing Invalid Objects from the Database

After installing the new version of BRM, run the create_procedures script to remove any invalid objects in the BRM database.

In a multischema system, perform this task on the primary Oracle DM machine.

To run the create_procedures script:

  1. Go to the BRM_home/sys/dm_oracle/data directory.

  2. Run the following command, which opens SQL*Plus:

    sqlplus login@ORACLE_SID
Enter password: password

    where:

    • login is the user name for the BRM database schema.

    • password is the password for the specified user name.

    • ORACLE_SID is the database alias of the BRM database schema.

  3. Run the following command:

    @create_procedures_character_set.plb

    where character_set specifies the database character set of either UTF8 or AL32UTF8.

Modifying the Root Encryption Key

To enhance security, you should modify the root encryption key on a regular basis.

See the appropriate section for more information:

Modifying the Root Encryption Key on Single-Schema Systems

To modify the root encryption key on single-schema systems:

  1. Back up the CRYPTKEY_T and WALLET_FILE_STORAGE_T tables in the BRM database. See your database documentation for more information on performing database table and view backups.

    Note:

    Store the backup in a safe location. The data in the backed up CRYPTKEY_T table and the root key wallet will become necessary if you encounter any issues in modifying the root encryption key.

  2. Go to the directory in which you installed the BRM server, and edit the appropriate source.me file:

    1. For Bash shell, edit the source.me.sh file and look for the following text: 

      export BRM_WALLET

      Update the wallet location to read:

      export BRM_WALLET=$PIN_HOME/wallet/

    2. For C shell, edit the source.me.csh file and look for the following text: 

      setenv BRM_WALLET

      Update the wallet location to read:

      setenv BRM_WALLET $PIN_HOME/wallet/

  3. Source the file you just edited:

    1. Bash shell:

      source source.me.sh

    2. C shell:

      source source.me.csh

  4. Run the following command from the BRM_home/sys/test directory. 

    pin_crypt_app -genrootkey

  5. Ensure that the testnap utility works.

  6. Run the following command from the BRM_home/sys/test directory. 

    pin_crypt_app -useZT -genkey -update_dm_conf

  7. Restart the CM and DM and ensure that the testnap utility works.

Modifying the Root Encryption Key on Multischema Systems

To modify the root encryption key on multischema systems:

  1. Back up the CRYPTKEY_T and WALLET_FILE_STORAGE_T tables in the BRM database in the primary schema and the CRYPTKEY_T table and WALLET_FILE_STORAGE_T view in all of the secondary schemas. See your database documentation for more information on performing database table and view backups.

    Note:

    Store the backup in a safe location. The data in the backed up CRYPTKEY_T table and the root key wallet will become necessary if you encounter any issues in modifying the root encryption key.

  2. Go to the directory in which you installed the BRM server on the primary and all secondary instances, and edit the appropriate source.me file:

    1. For Bash shell, edit the source.me.sh file and look for the following text: 

      export BRM_WALLET

      Update the wallet location to read:

      export BRM_WALLET=$PIN_HOME/wallet/

    2. For C shell, edit the source.me.csh file and look for the following text: 

      setenv BRM_WALLET

      Update the wallet location to read:

      setenv BRM_WALLET $PIN_HOME/wallet/

  3. Source the file you just edited:

    1. Bash shell:

      source source.me.sh

    2. C shell:

      source source.me.csh

  4. Verify that the key value in CRYPTKEY_T is the same for both the primary and secondary schemas. If it is not:

    1. Copy the value of pin_crypt_aes4dm from BRM_home/sys/dm_oracle/pin.conf to the same location on all of the secondary instances.

    2. Restart the BRM services on the primary and secondary BRM instances.

    3. Run the following command from the BRM_home/sys/test directory in the primary instance: 

      pin_crypt_app -useZT -genkey -update_dm_conf

    4. Copy the value of pin_crypt_aes4dm from BRM_home/sys/dm_oracle/pin.conf to the same location on all of the secondary instances.

    5. Restart the BRM services on the primary and secondary BRM instances.

    6. Run the following command from the BRM_home/apps/pin_crypt directory in the primary instance: 

      pin_crypt_upgrade -a

    7. Ensure that the testnap utility works.

  5. If the key value is the same for both the primary and secondary schemas, update the root key by doing the following:

    1. Run the following command from the BRM_home/sys/test directory: 

      pin_crypt_app  -genrootkey

    2. Ensure that the testnap utility works.

    3. Run the following command from the BRM_home/sys/test directory: 

      pin_crypt_app -useZT -genkey -update_dm_conf

    4. Restart the CM and DM in the primary instance and ensure that the testnap utility works.

    5. Copy the value of pin_crypt_aes4dm from BRM_home/sys/dm_oracle/pin.conf to the same location on all of the secondary instances.

    6. Verify that the key value in CRYPTKEY_T is the same for both the primary and secondary schemas.

    7. Restart the CM and DM in the secondary instances.

    8. Ensure that the testnap utility works.

Setting the Bill State for Preexisting Bills

If you are upgrading from BRM 12.0 Patch Set 4 or earlier, after the upgrade any new /bill objects include the PIN_FLD_STATE field set to the appropriate value. For all /bill objects that existed in the system before applying the BRM patch set, this field will be set to UNDEFINED.

You can optionally run a stored procedure to update the value of PIN_FLD_STATE on preexisting bills. This has no impact on functionality but can be done for consistency.

To run the stored procedure:

  1. Go to the BRM_home/sys/dd/data directory.
  2. Connect to the Oracle database with SQL*Plus:
    % sqlplus login@ORACLE_SID
Enter password: password

    where:

    • login is the user name for the BRM database schema.
    • password is the password for the specified user name.
    • ORACLE_SID is the database alias of the BRM database schema.
  3. Run this command:
    SQL> @update_bill_state_12PS5.source

The value is set according to the following conditions:

Condition PIN_FLD_STATE Value
The value of PIN_FLD_END_T is 0 INPROGRESS
The value of PIN_FLD_DUE is not zero and is greater than or equal to the value of PIN_FLD_CURRENT_TOTAL NEW
The value of PIN_FLD_DUE is not zero and is less than the value of PIN_FLD_CURRENT_TOTAL PARTIALLYPAID
The value of PIN_FLD_DUE is zero. SETTLED

See "About Bill States" in BRM Concepts for more information about these bill states.

Migrating Tax Codes

If you are upgrading from BRM 12.0 Patch Set 4 or earlier, after the upgrade tax codes are stored in the /config/taxcodes_map object rather than in the taxcodes_map file.

If you are upgrading from BRM 12.0 Patch Set 4 or earlier, the Patch Set installer loads the /config/taxcodes_map object with default values. You must migrate any existing tax codes from the taxcodes_map file to the /config/taxcodes_map object.

To migrate your existing tax codes to so, perform the following steps:

  1. If your existing BRM system contains multiple taxcodes_map files, collate them into a single file.

  2. Run the convert_taxcode.pl script to convert your existing tax codes into XML format: 

    perl BRM_home/setup/scripts/convert_taxcode.pl inputFile [outputFile]

    where:

    • inputFile is the name and location of the file that contains your tax code configurations from Patch Set 4 or earlier. By default, these tax codes are stored in the BRM_home/sys/cm/taxcodes_map file.

    • outputFile is the name of the output file to generate. This file will contain your tax codes converted into XML format. If not provided, the output file will be named config_taxcodes_map.xml.

  3. Copy the generated config_taxcodes_map.xml file to the BRM_home/sys/data/config directory.

  4. Load the config_taxcodes_map.xml file into the BRM database: 

    BRM_home/apps/load_config/load_config -M BRM_home/sys/data/config/config_taxcodes_map.xml

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

Your tax codes have been loaded into the /config/taxcodes_map object.

Updating pin_inv_doc_gen Infranet.properties

If you are upgrading from BRM 12.0 Patch Set 4 or earlier, after the upgrade entries in the pin_inv_doc_gen Infranet.properties file have changed.

Copy the changes from the BRM_home/apps/pin_inv_doc_gen/Infranet.properties.sample file to your BRM_home/apps/pin_inv_doc_gen/Infranet.properties file, and then set the following new entries:

  • infranet.schedulerdb.url: Specifies the scheduler database URL in the following format: 

    jdbc:oracle:thin:hostname:port/service

    where hostname is the hostname of the scheduler database, port is the port number for the scheduler database, and service is the service name of the scheduler database.

  • infranet.schedulerdb.user: Specifies the user name for the scheduler database.

  • infranet.schedulerdb.credentials: Specifies the security credentials for connecting to the scheduler database.

  • infranet.jdbcpool.size: Specifies the initial number of connections maintained in the pool. The default is set to the same as burst.threadpool.size.

  • infranet.jdbcpool.maxsize: Specifies the maximum number of connections that can be created. The default is set to the same as burst.threadpool.maxsize.