This chapter describes how to migrate Oracle Communications Billing and Revenue Management (BRM) accounts located within the same Oracle IMDB Cache grid.
Before attempting to migrate such account data, you should be familiar with the following topics:
Account Migration. See "Understanding Account Migration".
Oracle IMDB Cache Manager. See "Managing IMDB Cache-Enabled Systems".
Migration of account data within an Oracle IMDB Cache grid consists of migrating the data associated with selected accounts from a logical partition in the cache grid to a destination logical partition located in the same cache grid.
You migrate accounts between two logical partitions in one Oracle IMDB Cache grid when accounts drastically increase (or decrease) in one logical partition in the cache grid or when you add a logical partition to the cache grid. See "Using the Oracle IMDB Cache Grid to Partition Data" for more information.
When you add a logical partition to an Oracle IMDB Cache grid, you migrate accounts from each of the existing logical partitions to the newly-created logical partition to reset the load balance in that cache grid.
For example, if your system uses logical partitioning and you have two logical partitions in your database schema, the first logical partition is identified as 0.0.0.1 and the second logical partition as 0.1.0.1. The data stores (that is, the Oracle IMDB Caches) associated with these logical partitions are identified as tt_0.0.0.1 and tt_0.1.0.1 respectively.
Continuing with this example, suppose that you maintain 100 accounts in that Oracle IMDB Cache grid by storing 50 accounts in the data stores associated with each of its two logical partitions. A promotion effort results in the addition of 50 new accounts to that cache grid. To better manage your customer accounts, you add a logical partition (identified as 0.2.0.1) to that cache grid. You then select 25 accounts from each of the existing partitions to be migrated to populate the new logical partition you added. You migrate the selected accounts by performing two migration operations, one from each of the existing Oracle IMDB Caches (logical partitions) to the new cache (the logical partition identified as 0.2.0.1) in that cache grid. At the end of the two-step operation, the three data stores associated with the logical partitions in the cache grid carry an even load (with each data maintaining the data for 50 accounts).
BRM provides the pin_amt_tt utility for the migration of accounts between logical partitions in the same IMDB Cache grid.
The pin_amt_tt utility is a standalone utility and is installed as part of the Account Migration Manager installation. It is used to move accounts between the data stores associated with one Oracle IMDB Cache grid only.
The pin_amt_tt utility migrates the accounts using the values in the pin.conf configuration file that you provide for that migration task. This configuration file informs the utility about the accounts to migrate and the access information for the source and destination locations within that cache grid.
At the start of the migration, the pin_amt_tt utility fetches the list of account POIDs it must migrate. This list of accounts is based on the selection criteria you provided in the utility's pin.conf file.
It locks the associated cached information on the selected accounts to prevent all authentication, authorization, and accounting (AAA) activity on those accounts. If any non-AAA operations are currently being performed on those accounts, BRM waits for those processes to finish.
The utility then makes the entries in the uniqueness table (in the BRM database) invalid for these accounts so as to prevent access to the data in them through any uniqueness reference.
It unloads the accounts from the source Oracle IMDB Cache, ensures that the BRM database contains the current data, and loads them into the destination Oracle IMDB Cache.
The utility updates the entries in the uniqueness table (in the BRM database) to point each migrated account to its appropriate destination cache location.
For example, for an account 2286 located in the logical partition identified by 0.0.0.1, the entry in the uniqueness table is 0.0.0.1 /account 2286 0. This account is migrated to the logical partition identified by 0.2.0.1. When the uniqueness table entries are updated to point to the new location, the entry for this account changes from 0.0.0.1 /account 2286 0 to 0.2.0.1 /account 2286 0.
It migrates the related transient objects (active-session objects and reservation objects) from the source Oracle IMDB Cache to the destination Oracle IMDB Cache.
The following tables make up the transient objects migrated by the pin_amt_tt utility:
Active-Session objects:
ACTIVE_SESSION_T
ACTIVE_SESSION_TELCO_GSM_T
ACTIVE_SESSION_TELCO_GPRS_T
ACTIVE_SESSION_TELCO_T
ACTIVE_SESSION_RESV_LIST_T
Reservation objects:
RESERVATION_T
RESERVATION_BALANCES_T
When you use the pin_amt_tt utility to migrate accounts, you can enable or disable account synchronization in the instance of the Pipeline Manager associated with the BRM database. You do so by enabling or disabling the pipeline_sync configuration parameter in the utility's pin.conf file.
If you enabled the pipeline_sync configuration parameter, then, after the pin_amt_tt utility migrates the accounts to the destination logical partition in the Oracle IMDB Cache grid, it generates an UpdateLogicalPartition notification event. A message is added in the appropriate database queue for the Pipeline Manager instance associated with the BRM database.
The pin_amt_tt utility does not wait for any acknowledgment from the Pipeline Manager. The pipeline for the BRM database is automatically updated with the database information on the migrated accounts.
The message enqueued in the database queue for the pipeline contains information about the new destination to which the accounts were migrated and the access details for the destination Oracle IMDB Cache. When you migrate a large number of accounts, the utility breaks up the account entries into multiple messages.
The fields in the message are:
PIN_FLD_ACCOUNT_TAG, which is a comma-separate list of the POIDs of the migrated objects.
PIN_FLD_DEST_DATABASE, which identifies the destination logical partition.
For example, the message enqueued for accounts 352690, 359678, and 360254, which were moved to the logical partition identified as 0.2.0.1, would be as follows:
PIN_FLD_DEST_DATABASE STR [0] "0.2.0.1" PIN_FLD_ACCOUNT_TAG STR [0] "352690,359678,360254"
You may have completed some of the following requirements needed to run the pin_amt_tt utility, as part of the general installation tasks. Verify the following:
General system requirements. See "Installing and Configuring BRM for Account Migration".
Oracle TimesTen 64-bit client software is installed. See Oracle TimesTen In-Memory Database Installation Guide for information.
Installation required to send BRM events to your pipelines for Account Synchronization is complete. See "About Sending Account Data to Pipeline Manager" in BRM Installation Guide.
All other configuration relating to Pipeline Manager that would pertain to account migration and synchronization within an Oracle IMDB Cache. See "Migrating Accounts with the Pipeline Manager Running".
The load_pin_uniqueness utility has been configured correctly. See "Configuring the load_pin_uniqueness Utility for Oracle IMDB Cache".
The following points should be noted when you migrate account data using the pin_amt_tt utility:
The destination Oracle IMDB Cache must be in an active state.
The following operations may fail during the migration process on accounts selected for migration:
AAA opcodes
Payment
Billing
If you require account synchronization with Pipeline Manager (that is, pipeline_sync is set to 1 in pin.conf file), then, to avoid load failures in Rated Event loader:
Stop the Batch Controller before the migration process begins.
Start the Batch Controller after the migration process finishes.
Customer Center should not be operational during the account migration.
Close the Customer Center client application before you start the migration process and reopen it after you verify that the migration was successfully completed.
Allow sufficient time for the pin_amt_tt utility to wait on accounts that have been selected for migration but are currently locked by another application.
Important:
Specify the desired waiting time as the value for LockWait in the sys.odbc.ini data store configuration file you created in IMDB_home/info, where IMDB_home is the directory in which you installed Oracle IMDB Cache.For more information, see "Installing and Configuring a BRM System with IMDB Cache Manager".
Migrating accounts includes the following general procedure. When you move accounts from more than one logical partition to a destination logical partition within the same Oracle IMDB Cache grid, there will be a repetition of the procedure with some changes to suit the specific account migration.
The procedure to migrate a set of selected accounts within the same cache grid consists of the following steps:
Verify that your migration follows the recommended guidelines. See "Guidelines for Migrating Accounts with the pin_amt_tt Utility".
Verify that you have configured the pin.conf file with the required information. See "Configuring the pin_amt_tt Utility".
Start the account migration application. See "Running the pin_amt_tt Utility".
Monitor the migration. See "Monitoring Account Migration".
Handle any failures that occurred during the migration process. See "Handling Account Migration Failures"
Clean up the destination Oracle IMDB Cache of all old and unnecessary objects. See "Cleaning Up the Oracle IMDB Cache after Migration"
BRM provides a default pin.conf configuration file in the BRM_home/sys/amt_tt directory. Each time you run the pin_amt_tt utility, edit the appropriate pin.conf file. See "Creating Configuration Files for BRM Utilities" for more information.
Note:
Before you make any changes to the pin.conf file, save a backup copy. When editing this file, follow the instructions in each section.The pin.conf file should contain the required information for the following:
Access information for the Connection Manager.
Access information about the Oracle Database where all your data is stored.
Access information for the data store associated with the logical partition where the selected accounts currently reside.
Access information for the data store associated with the logical partition to which accounts are to be migrated.
Selection criteria for the set of accounts you are migrating. See "Providing the Account Selection Criteria" for more information.
Whether Account Synchronization is enabled.
The desired logging level and file information.
Table 36-1 provides information on all the parameters used in the pin.conf file.
The pin.conf file provides a set of entries that can be used to provide selection criteria to be used by the pin_amt_tt utility in selecting accounts for migration.
Provide a filter for the account selection by providing values for one, some, or all the criteria listed in the file. The utility migrates only those accounts that fulfill all the criteria you provide in the pin.conf file. The pin_amt_tt utility requires a value to be set for at least one of the account selection criteria in the configuration file.
By default, all the available account selection criteria are commented out in the pin.conf file. Uncomment the entry for each criteria that you require and provide a value for it in the pin.conf file.
Table 36-1 shows the parameters used in defining the pin.conf configuration file.
Table 36-1 pin.conf Values used by pin_amt_tt
| Entry | Value | Description |
|---|---|---|
|
account_status |
String |
Specifies the status for the accounts that would be fetched for migration. The default is Active. For example: - pin_amt_tt account_status Active |
|
bill_day_of_month |
Date |
Specifies the billing DOM. Accounts with this billing DOM are fetched for migration. The default is 1. For example: - pin_amt_tt bill_day_of_month 1 |
|
cm_ptr |
String |
Specifies the connection information of the CM process. |
|
end_creation_date |
Date |
Specifies the end date for the range of account creation dates to be used as selection criteria. Enter as MM/DD/YYYY. For example: - pin_amt_tt end_creation_date 01/31/2011 |
|
logfile |
String |
Specifies the path to the log file for the sample application. |
|
loglevel |
Integer |
Specifies the level for the log:
|
|
login_name |
String |
Specifies the login name to use to connect to CM process. |
|
login_pw |
String |
Specifies the password to log in to the Connection Manager (CM) process. |
|
login_type |
Integer 0 or 1 |
Specifies whether the login name and password are required. The value for this entry can be:
|
|
max_accounts |
Positive integer |
Specifies the maximal number of accounts to include in the selection. For example: - max_accounts 100 |
|
oracle_db_pwd |
String |
Mandatory parameter. Specifies the user password for logging into an Oracle database. |
|
oracle_db_sid |
String |
Mandatory parameter. Specifies the Oracle Service ID for logging into an Oracle database. |
|
oracle_db_user |
String |
Mandatory parameter. Specifies the user name for logging into an Oracle database. |
|
pipeline_sync |
Integer 0 or 1 |
Specifies whether synchronization between Pipeline and AMT_TT is needed or not.When set to 1, the UpdateLogicalPartition notification is created after the migration process is complete. The default is 0 (synchronization is not required). For example: - pin_amt_tt pipeline_sync 0 |
|
poid_list |
string |
A comma-separated list of account POID values. The maximum number of POID entries allowed in this list is 1000. For example: - poid_list 441837,441838 |
|
retry_count |
Integer |
Specifies the number of attempts for the Load, Unload, or UpdateUniqueness attempts. The default is 3. For example: - pin_amt_tt retry_count 3 |
|
source_tt_node_db_id |
String |
Mandatory parameter. Specifies the database number for a source Oracle IMDB Cache (data store). For example: - pin_amt_tt source_tt_node_db_id 0.0.0.1 |
|
source_tt_node_dsn |
String |
Mandatory parameter. Specifies the data store name for a source Oracle IMDB Cache (data store). For example: - pin_amt_tt source_tt_node_dsn tt_0.0.0.1 |
|
source_tt_node_pwd |
String |
Mandatory parameter. Specifies the user password for logging into a source Oracle IMDB Cache (data store). For example: - pin_amt_tt source_tt_node_pwd pinXX |
|
source_tt_node_user |
String |
Mandatory parameter. Specifies the user name for logging into a source Oracle IMDB Cache (data store). For example: - pin_amt_tt source_tt_node_user pinXX |
|
start_creation_date |
Date |
Specifies the start date for the range of account creation dates to be used as selection criteria. Enter as MM/DD/YYYY. For example: - pin_amt_tt start_creation_date 01/01/2011 |
|
target_tt_node_db_id |
String |
Mandatory parameter. Specifies the database number for a destination Oracle IMDB Cache (data store). |
|
target_tt_node_dsn |
String |
Mandatory parameter. Specifies the data store name for a destination Oracle IMDB Cache (data store). |
|
target_tt_node_pwd |
String |
Mandatory parameter. Specifies the user password for logging into a destination Oracle IMDB Cache (data store). |
|
target_tt_node_user |
String |
Mandatory parameter. Specifies the user name for logging into a destination Oracle IMDB Cache (data store). |
|
Userid |
String |
Specifies the database number and service type for the Portal database. |
To run the pin_amt_tt utility
Go to the BRM_home/sys/amt_tt directory where the pin.conf file is located.
Enter the following command.
pin_amt_tt
The account migration process begins.
The pin_amt_tt utility makes log entries in its log file. Access the log file for this utility and monitor the account migration to verify that:
The cache groups were unloaded from the source Oracle IMDB Cache.
The accounts were migrated to the destination Oracle IMDB Cache.
The transient objects were migrated to the destination Oracle IMDB Cache (data store). See "About the Transient Objects Migrated by the pin_amt_tt Utility" for information on the tables migrated by this utility.
The data from the BRM database was loaded into the cache groups located in the destination Oracle IMDB Cache grid node.
The actions BRM takes depend on where the failure occurs in the migration process:
If there are any problems in migrating the accounts data, the migration changes are rolled back and your system is restored to the state before the migration.
Check the log file and take the necessary actions before you attempt the migration again. The log file is in the directory specified by the logfile entry in the pin.conf file. See Table 36-1.
If the migration fails for the active-session objects associated with any of the selected accounts, BRM rolls back the migration of all the active-session objects. It does not try to migrate the reservation objects.
Manually migrate the required active-session and reservation objects for the required accounts. Use the POID information in the log file to identify these objects.
If the migration succeeds for the active-session objects, but fails for the reservations objects associated with any of the selected accounts, BRM rolls back the migration of all the reservation objects.
Manually migrate the reservation objects for the required accounts. Use the POID information in the log file to identify these objects.
Complete the following steps to migrate the transient objects for the required accounts:
Use the POID information in the log file to identify the appropriate transient objects for the accounts.
Use SQL statements to migrate those transient objects to the destination Oracle IMDB Cache.
See "About the Transient Objects Migrated by the pin_amt_tt Utility" for the set of transient objects migrated by the pin_amt_tt utility.
When you run the pin_purge utility on the Oracle IMDB Cache, the cache gets cleared of all unnecessary data objects. However, these objects remain archived in the BRM database.
After the migration, when the pin_amt_tt utility loads all the entries for the migrated accounts from the BRM database into the Oracle IMDB Cache, the cache groups for the migrated accounts include the archived data.
To clear up the unnecessary information on the migrated accounts from the Oracle IMDB Cache, use the pin_purge utility. See "pin_purge" for more information.