32 Understanding Account Migration

This chapter provides an overview of account migration in Oracle Communications Billing and Revenue Management (BRM). It describes the Account Migration Manager (AMM) application, including how AMM interacts with your BRM database.

Before migrating accounts, you should be familiar with the following topics:

About Account Migration

Account migration consists of migrating (or transferring) the data associated with selected accounts from their source storage location to a destination storage location.

BRM migrates account data based on account migration information composed of details on the selected accounts and access information for the source and destination locations of those accounts. You provide this information to the utility you use to perform the migration.

When you store data only in the BRM database, the migration process moves the data associated with the selected accounts from the source database schema to a destination schema.

When you use Oracle IMDB Cache Manager in your system, this migration process includes the Oracle IMDB Cache associated with the source BRM database schema and the Oracle IMDB Cache associated with the destination BRM database schema. After the migration process ends, the destination BRM database schema holds the account information for the migrated accounts and the destination Oracle IMDB Cache holds the critical data for the migrated accounts.

When you use Oracle IMDB Cache Manager, you sometimes migrate account data from one Oracle IMDB Cache instance to another within the same Oracle IMDB Cache grid. In that case, the storage location of the account data in the BRM database remains unchanged. The migration process ensures that the database table entries are updated accordingly. After the migration, when you modify the cached data for an account in its new Oracle IMDB Cache location, the appropriate data in the BRM database is updated. The synchronization between the cached data in Oracle IMDB Cache and the corresponding data in the BRM database is maintained and no data is lost.

When to Migrate Accounts

You migrate account objects to redistribute the data in the following situations:

  • One BRM database schema contains significantly more or fewer accounts than other BRM database schemas (for example, when you add a schema to an existing multischema system).

  • The number of events per account is significantly greater in one schema than in other schemas.

  • The time it takes to complete a billing run becomes erratic.

  • A node is added to an Oracle IMDB Cache grid.

About Account Migration Processes

The process you choose for an account migration task depends on the current storage location of the account objects selected for migration. The possible scenarios are as follows:

Account Migration Involving Only the BRM Database

If you configured your BRM environment with only the BRM database, you use the AMM application to perform all account migration tasks. You provide information on the accounts to migrate and the access details for the source database schema and the destination schema. See "About the AMM Application".

Account Migration Involving a BRM Database and an Oracle IMDB Cache

If you configured your BRM environment with Oracle IMDB Cache Manager, the accounts selected for migration are stored in a BRM database schema and their critical data might be located in the Oracle IMDB Cache associated with that database schema.

This migration consists of the following steps:

  1. You use the AMM application to perform account migration from the source BRM database schema to the destination BRM database schema. See "How AMM Works with Oracle IMDB Cache Manager in the BRM Environment".

  2. After the application completes the migration, you store the critical data for the migrated accounts in the destination Oracle IMDB Cache by using the appropriate SQL script created and stored during the installation process. See "Loading Destination Oracle IMDB Cache with Data from BRM Database".

Account Migration Between the Logical Partitions in One IMDB Cache Grid

In this scenario, you are redistributing data between the Oracle IMDB Caches (logical partitions) within one Oracle IMDB Cache grid only.

You use the pin_amt_tt utility to move the accounts between the Oracle IMDB Caches in one Oracle IMDB Cache grid. The account data in the BRM database is not migrated. See "Migrating Accounts within an Oracle IMDB Cache Grid".

You can set up synchronization between Pipeline Manager and the pin_amt_tt utility by modifying the configuration file used by this utility. See "About Account Synchronization with Pipeline Manager after the Migration".

Scheduling Account Migration

You achieve optimal migration performance and the smallest impact to your operations if you schedule migrations for maintenance windows. If you must migrate a large number of accounts but your maintenance window is only a couple of hours, you can perform migrations over a period of several days. The AMM software processes jobs in stages, enabling you to pause and resume account migration without affecting database integrity.

For information on scheduling migration, see "Automating Account Migration".

About the AMM Application

AMM is an application that migrates accounts and all of their associated objects from a source schema in a BRM database to a destination schema in the same database.

How AMM Works

The AMM software migrates accounts based on information you provide in the account search configuration file for that migration task.

In this file, you specify a group of accounts to migrate based on specific criteria, such as account creation date or account status. The group of accounts and associated objects that meet this criteria forms a job.

Jobs are processed by the AMM software through a queue system, with each job processed in the order received. To improve migration performance, jobs are subdivided into batches, which contain a configurable number of accounts.

Batches are assigned to a configurable number of threads, which process the batches in parallel. Each batch is migrated in a single distributed transaction, during which time activity is prevented on the accounts in the batch. Depending on the success of the batch migration, changes to the database are either committed or rolled back.

How AMM Works with Oracle IMDB Cache Manager in the BRM Environment

When your environment includes the Oracle IMDB Cache Manager, data from a single database schema might be distributed among multiple logical partitions (also called Oracle IMDB Caches). As a result, accounts selected for migration might have data stored in one of the Oracle IMDB Caches associated with the source BRM database schema.

In addition to the information on the accounts to migrate, you provide the access details for the source Oracle IMDB Cache in the Infranet.properties configuration file.

Before the migration job starts, AMM locates the data in the source Oracle IMDB Cache (for the selected accounts), updates the corresponding data objects in the BRM database, and unloads the cache groups for the selected accounts from the source Oracle IMDB Cache. AMM migrates the selected account data from the source BRM database location to the destination BRM database location.

About Migrating Accounts When the Pipeline Manager Is Online

You can configure your system to migrate accounts when the Pipeline Manager is running. In this configuration, the Pipeline Manager temporarily stops call details record (CDR) processing for all accounts undergoing migration. See "Migrating Accounts with the Pipeline Manager Running".

By default, AMM does not support migration when your pipelines are running. You specify whether AMM can migrate accounts while the Pipeline Manager is online by using the controller_N_event_generation parameter in the AMM Infranet.properties file. See "Connecting AMM to Your Database Schemas".

Caution:

If you disable this option, you must shut down the Pipeline Manager before you migrate accounts. Otherwise, your pipelines might send account information to the wrong BRM database schema, causing incorrect account balances and revenue leakage.

Deleting Migrated Objects

For performance reasons, the AMM software does not automatically remove the migrated objects from the source database schema. Instead, it flags the migrated objects as invalid to prevent BRM applications from accessing them. You can use the AMM software to manually purge invalid objects from the database at any time.

About Migrating Hierarchical, Sponsorship, and Resource Sharing Accounts

You can configure AMM to migrate hierarchical, sponsorship, and resource sharing groups from a source BRM database schema to a destination schema. In this configuration, AMM does the following:

By default, group migration is disabled. You specify whether to migrate account groups by using the migration_mode entry in the account search file (BRM_home/apps/amt/account_search.cfg). See "Creating the Account Search Configuration File".

Caution:

When you enable group migration, you must perform extra verification steps to prevent accounts from being severed from their associated account group. See "Checking Account Group Details".

About Searching for Member and Nongroup Member Accounts

When you enable group migration, AMM searches for accounts in two phases:

  • In the first phase, AMM searches for nongroup member accounts only. That is, AMM excludes all remittance, sponsorship, hierarchical, branded, and resource sharing accounts from the account search. Accounts meeting the search criteria are divided into batches, and each batch is flagged as containing nongroup member accounts only.

  • In the second phase, AMM searches for accounts belonging to hierarchical, sponsorship, and resource sharing groups only. If an account meets the search criteria, AMM finds all other account members that are related to the account. These accounts are organized into an account group. See "About Account Groups".

    Each account group is divided into batches, which are assigned an account group ID and flagged as containing account group members.

    Note:

    AMM cannot migrate remittance or brand accounts. See "Brand and Remittance Accounts Not Migrated".

All accounts meeting the search criteria, both group member and nongroup member accounts, still form one job.

About Account Groups

An account group consists of all account members that are related to a specific account. When AMM finds an account that meets the search criteria, it finds the parent account and all other child accounts in the group. If one of the accounts is also a member of another group, it finds all members of the other group as well.

Figure 32-1 One Account Group

Description of Figure 32-1 follows
Description of ''Figure 32-1 One Account Group''

For example, in Figure 32-1, account A meets the search criteria. Because account A is a child in a hierarchy group, AMM finds the parent account and all child accounts in that hierarchy group. Because one hierarchy account member is also a member of a sponsorship group, AMM finds all accounts in the sponsorship group as well. In this example, the account group consists of all accounts in the hierarchy group and the sponsorship group.

About Migrating Account Groups

AMM migrates account group member and nongroup member batches in different ways. AMM migrates:

  • Batches containing nongroup members in one transaction. During migration, AMM disables all accounts that belong to a single batch.

    • If the batch migrates successfully, AMM commits the changes to all database schemas and enables the accounts in the destination schema.

    • If the batch fails to migrate, AMM rolls back the changes and re-enables the accounts in the source database schema.

  • Batches containing account group members by account group ID. AMM disables all accounts that belong to an account group before migration begins. After migration starts, AMM monitors whether all batches for the account group migrate successfully.

    • If all batches migrate successfully, AMM commits the changes to all database schemas and enables the accounts in the destination schema.

    • If even one batch in the group fails, AMM leaves all account group members disabled in both source and destination schemas. You must fix the error and use AMM to reprocess the job before your BRM system can access the accounts.

AMM Process Overview

Figure 32-2 shows the AMM process overview.

Figure 32-2 AMM Process Overview

Description of Figure 32-2 follows
Description of ''Figure 32-2 AMM Process Overview''

The account migration process can be divided into the following stages:

  1. The account search configuration file containing information on the accounts to migrate and access information for the source and destination database schemas is provided as input to the pin_amt utility. See "About the Account Search Configuration File".

  2. The pin_amt utility processes the account search configuration file.

    If accounts in the account search configuration file have data in the corresponding Oracle IMDB Cache grid, the pin_amt utility ensures that the data for those accounts is current in the BRM database.

  3. Every account to be migrated is set up as an individual job. The jobs are divided into batches and placed in the queue. See "About the pin_amt Utility".

  4. The AMM Controller allocates batches to threads and passes batches to the AMM Mover. See "About the AMM Controller".

  5. The AMM Mover migrates the batch of accounts by moving the associated data from the source schema to the destination schema. See "About the AMM Mover".

  6. If Oracle IMDB Cache Manager is used in the system, you update the cache groups in the logical partition of the destination Oracle IMDB Cache grid.

About the Account Search Configuration File

The account search configuration file provides the details on which accounts to migrate, their source and destination storage locations, and the size of each batch.

You can also migrate accounts based on custom criteria. See "Creating Custom Account Search Criteria".

About the pin_amt Utility

The pin_amt utility is a standalone utility which generates account migration jobs for the AMM Controller to process. This utility can perform all its functions, such as finding accounts to migrate and submitting and enabling jobs, whether the AMM Controller is online or offline.

You use the pin_amt utility to perform the following tasks:

  • Start, stop, resume, and monitor the AMM Controller.

  • Find all accounts in the source database schema that meet your search criteria.

  • Enable account migration jobs in the queue.

  • Delete jobs from the job management tables.

  • Purge invalid objects from the source schema.

When you submit an account search configuration file, the pin_amt utility does the following:

  1. Searches the source database schema for all accounts that meet the criteria in the account search configuration file, excluding all remittance accounts and all accounts that are part of branded, hierarchical, sponsorship, and resource sharing groups.

    For accounts that have data in a corresponding Oracle IMDB Cache, this utility does the following:

    1. Accesses the account data in the source Oracle IMDB Cache.

    2. Updates the data in the BRM database for those accounts with the data in the source cache.

    3. Unloads the cache groups associated with those accounts from that Oracle IMDB Cache.

  2. Divides the list of account POIDs into batches.

  3. Populates the job management tables in the primary, source, and destination schemas with the list of account POIDs to migrate. See "About AMM Job Management Tables".

  4. Determines whether group migration is enabled.

    • If group migration is enabled, pin_amt proceeds with steps 5 through 9.

    • If group migration is disabled, the account search is complete. The AMM Controller can begin processing the job when the job is enabled in the queue. See "About the AMM Controller".

  5. Searches all hierarchy, sponsorship, and resource sharing groups in the source schema for accounts that meet the search criteria.

  6. When an account meets the search criteria, pin_amt finds all other accounts related to the account and organizes them into an account group.

  7. Determines whether the size of the account group exceeds the maximum. If it does, AMM excludes the account group from the job.

    Note:

    You specify the maximum size of an account group by using the account search configuration file. See "Creating the Account Search Configuration File".
  8. Divides all members of one account group into batches. All batches in the group are assigned the same group ID and flagged as containing account group members.

  9. Populates the job management tables in the primary, source, and destination schemas with the list of account POIDs to migrate. See "About AMM Job Management Tables".

About the AMM Controller

The AMM Controller is a server process that checks the queue for jobs to process. By default, your system contains one AMM Controller, which processes one job at a time. For information about using multiple AMM Controllers, see "About Using Multiple AMM Controllers".

The AMM Controller processes group member and nongroup member batches in different ways:

How AMM Controller Processes Batches with Nongroup Members

When processing batches that contain nongroup members, the AMM Controller does the following:

  1. Assigns batches to threads, which run in parallel. Each thread processes one batch at a time. If there are more batches than threads, each thread must process multiple batches in sequence. You use a configuration file to configure the number of AMM Controller threads. See "Connecting AMM to Your Database Schemas".

  2. Changes the batch status to IN_PROGRESS. See "About Batch Status Flags".

  3. Passes the job ID, batch number, and schema qualifications name to the AMM Mover on the destination database schema for processing. See "About the AMM Mover".

  4. Determines whether the AMM Mover successfully migrated accounts.

    • If migration is successful, the AMM Controller commits the changes to all database schemas and changes the batch status to FINISHED. See "About Batch Status Flags".

    • If migration fails, the AMM Controller rolls back the changes and updates the batch status to FAILED. See "About Batch Status Flags".

How AMM Controller Processes Batches with Account Group Members

When processing batches that contain account group members, the AMM Controller does the following:

  1. Changes the account group status to GROUP_DISABLING. See "About Group Status Flags".

  2. Locks the appropriate base table records in the source database schema so that applications cannot access group member accounts during migration.

  3. Marks all account group members in the source schema as invalid.

  4. Determines whether all account group members were disabled in the source schema.

    • If all accounts were successfully disabled, the AMM Controller changes the account group status to GROUP_READY. See "About Group Status Flags".

    • If any accounts were not disabled, the AMM Controller changes the account group status to FAILED. See "About Group Status Flags".

  5. Changes the account group status to GROUP_IN_PROGRESS.

  6. Passes individual batches in the account group to the AMM Mover for processing.

    1. Assigns an individual batch in the group to a thread.

    2. Changes the batch status to IN_PROGRESS.

    3. Passes the job ID, batch number, and database link name to the AMM Mover. See "About the AMM Mover".

    4. Determines whether the AMM Mover successfully migrated the batch and sets the batch status to FINISHED or FAILED.

  7. Determines whether all batches in the account group migrated successfully.

    • If all batches migrated successfully, the AMM Controller enables all account group members in the destination database schema and changes the account group status to GROUP_FINISHED. See "About Group Status Flags".

    • If any batch failed to migrate, the AMM Controller changes the account group status to GROUP_FAILED. See "About Group Status Flags".

      Important:

      When an account group fails to migrate, all its accounts remain disabled in the source and destination schemas. You must fix the error and migrate the job again before your BRM system can access the accounts.

About the AMM Mover

The AMM Mover is the process that actually moves accounts from one database schema to another. Each schema contains at least one AMM Mover.

Note:

The AMM Mover performs the following functions regardless of whether a batch contains group-member or nongroup member accounts.

When the AMM Mover receives a batch, it does the following:

  1. Locks the appropriate base table records in the source database schema so that applications cannot access accounts during migration.

  2. Migrates the objects for an account batch from the source schema to the destination schema in a single distributed transaction. See "About Distributed Transactions".

  3. Marks all migrated objects in the source schema as invalid.

  4. Updates the account POIDs in the uniqueness table to reflect the account's new location. For example, if an account is migrated from schema 0.0.0.1 to schema 0.0.0.2, the account POID changes from 0.0.0.1 /account 2286 0 to 0.0.0.2 /account 2286 0.

About Distributed Transactions

The AMM software migrates each batch of accounts as a single distributed transaction by using schema qualifications. Hence, changes can be made to the primary, source, and destination database schemas and then committed or rolled back in one transaction, ensuring the integrity of the database.

Figure 32-3 shows the schema qualifications for a multischema system with three database schemas, one AMM Controller, and two threads:

Figure 32-3 AMM Database Schema Connections

Description of Figure 32-3 follows
Description of ''Figure 32-3 AMM Database Schema Connections''

Account Migration Restrictions

When you run the AMM software, be aware of the following restrictions:

Account Activity Prevented during Account Migration

To prevent applications from accessing or modifying accounts that are being migrated, AMM locks the accounts in Oracle. Only one batch of accounts per thread is locked at a time and only while the accounts are being physically migrated.

Note:

When migrating account groups, AMM locks all accounts in the account group before migration begins.

If an application attempts to access a locked account, the Oracle Data Manager (DM) returns a PIN_ERR_INVALID_OBJECT error.

Do Not Rerate Events during Account Migration

Because the AMM software may suspend some events that you want to rerate, you must not rerate pipeline events during account migration.

Do Not Alter Account Group Members

AMM checks account group relationships only when you first create a job, and does not reverify relationships during the migration process. Therefore, once an account group is included in a migration job, you:

  • Must not add members to the account group

  • Must not modify relationships between account group members

If you must alter an account group after it is included in a job but before the job completes migration, you must:

  1. Delete the migration job.

  2. Modify the account group.

  3. Re-create the account migration job.

Migration Prevented during Account Activity

AMM does not migrate accounts while they are being accessed or modified by BRM or another application. For best performance, stop all account activity before you migrate accounts.

If you cannot restrict all access to the accounts in your database schemas, AMM can still process account migration jobs. However, AMM does not migrate any batch that contains active accounts. You can check for failed batches and resubmit them for migration once account activity stops.

Brand and Remittance Accounts Not Migrated

You can migrate accounts based on a variety of criteria, including account status, account creation date, and product name. However, the AMM software always excludes brand and remittance account from account migration jobs.

Unique POIDs Required across All Database Schemas

The AMM software can migrate only accounts that have a unique POID. Starting with Infranet Release 6.2 ServicePak 1, the multischema software automatically creates unique POIDs across all database schemas in your system.

If your database contains accounts created both before and after you installed Release 6.2 ServicePak 1, AMM migrates only those accounts created after you installed 6.2 ServicePak 1. For information on how to migrate accounts created before 6.2 ServicePak 1, contact your Oracle BRM representative.

Important:

If your BRM system uses a custom POID generation scheme, make sure the sequence number generation algorithm creates unique POIDs across all of your database schemas.

Transient Objects Are Not Migrated

While the pin_amt utility migrates account objects, it does not migrate any transient objects.

Some Client Applications May Fail during Account Migration

BRM client applications, such as Customer Center, Payment Tool, and Self-Care Manager, may generate error messages and fail to commit changes to the database during account migration. For example, if a CSR opens an account in Customer Center just before the account being migrated to another database schema, Customer Center generates an ”Unable to process account” and ”ERR_INVALID_OBJECT” error message when the CSR attempts to save any changes to the account.

In that case, the CSR must restart Customer Center and access the account again so it retrieves the account's new location.

Important:

If your system contains custom client applications that connect to the BRM database and search accounts based on POID, you must modify your application. See "Modifying Custom Client Applications for AMM".

AMM Does Not Support Some BRM Components

Currently, you cannot use AMM to migrate accounts if your BRM system includes any of the following optional components:

  • LDAP Manager

  • RADIUS Manager

Using BRM Reports after Migration

To use BRM Reports after you migrate accounts, you must use BRM Reports Release 6.2 ServicePak 1 or later. If you use an earlier version of BRM Reports with AMM, your reports will retrieve and process duplicate data from your source and destination database schemas.

For example, if an account object is migrated from schema 0.0.0.1 to schema 0.0.0.2, earlier versions of BRM Reports retrieve the account object from both schemas while BRM Reports 6.2 ServicePak 1 and later retrieve the account object only from schema 0.0.0.2.

For information on how to modify custom reports to work with AMM, see "Modifying Custom BRM Reports for AMM".

About Using Multiple AMM Controllers

Caution:

Implementing multiple AMM Controllers is for advanced users only. Use multiple AMM Controllers only if you understand the impact to migration performance.

Using multiple AMM Controllers enables you to process multiple account migration jobs in parallel. However, you receive performance improvements only in the following situations:

  • Your system contains more than three database schemas.

  • No two migration jobs use the same schema at the same time.

When multiple jobs use the same schema, as shown in Figure 32-4, migration performance degrades significantly.

Figure 32-4 Concurrent Database Use Performance Degradation

Description of Figure 32-4 follows
Description of ''Figure 32-4 Concurrent Database Use Performance Degradation''

For more information, contact your Oracle BRM representative.

Account Migration Performance

Account migration is resource intensive and can overload your BRM system.

Signs that your system is overloaded during account migration:

  • Batch processing times steadily increase, without returning to their initial processing times.

  • The AMM software is processing fewer than five accounts per second.

  • You receive a distributed transaction time-out error (Oracle error 2049).

  • There are a high number of waits for undo segment extension and latch free operations.

If your system exhibits any of these signs, you must tune your Oracle database. For guidelines, see "Tuning Your Database for Optimal Account Migration Performance" or contact your Oracle BRM representative.

About AMM Job Management Tables

Job management tables are created on your database schemas during installation and are populated with information about each migration job.

The AMM installer creates the tables listed in Table 32-1 on your schemas:

Table 32-1 AMM Job Management Tables

Table Name Schema Description When Populated

AMT_ACCOUNT_BATCH_TABLE_T

Primary only

Stores the list of tables containing data to migrate for a particular batch.

Populated by the AMM Mover when it migrates a particular batch.

AMT_METADATA_T

All schemas

AMM data dictionary. This lists all default BRM tables and any custom tables you created.

If you add any tables after you install AMM, you must refresh the AMM data dictionary. See "Configuring AMM for New Custom Tables".

During installation and when you run pin_amt_install.pl -m to refresh the AMM data dictionary.

AMT_POID_TYPE_MAP_T

All schemas

Maps the POID type to the table name. This table is static.

During installation and when you run pin_amt_install.pl -m to refresh the data dictionary.


About Job Status Flags

The AMM software sets jobs to a status listed in Table 32-2. You can see a job's status by running a list_jobs report. See "Monitoring Job Status".

Table 32-2 Job Status Flags

Status Description

DISABLED

The job has been submitted but not enabled.

NOT_PROCESSED

The account migration job is enabled and waiting in the queue to be processed.

PRE_MIGRATION_WAITING

AMM is notifying the account-router Pipeline Manager to suspend events for all accounts in the job.

PRE_MIGRATION

The account-router Pipeline Manager acknowledged that it is suspending events for all accounts in the job. AMM is waiting a specified amount of time before starting migration.

READY

The job is ready to be processed.

IN_PROGRESS

The job is being processed by the AMM Controller.

FAILED

The job has been aborted.

BAL_MIGRATED

The account discount balance migrated successfully.

POST_MIGRATION_WAITING

AMM is notifying the account-router, source, and destination instances of the Pipeline Manager that the job migrated successfully.

POST_MIGRATION

The account-router, source, and destination instances of the Pipeline Manager acknowledged that they updated all account information in their caches.

PRE_JOB_RECYCLE

AMM is notifying the account-router Pipeline Manager to resume processing events for accounts in the job.

JOB_RECYCLE

The account-router Pipeline Manager acknowledged that it is ready to begin reprocessing events for accounts in the job.

FINISHED

The job has completed successfully.


About Batch Status Flags

AMM sets account batches to a status listed in Table 32-3. You can check a batch's status by running a job_details report. See "Checking Job Details".

Table 32-3 Batch Status Flags

Status Description

NOT_PROCESSED

The account batch has not yet been migrated.

IN_PROGRESS

The account batch is currently being migrated.

FAILED

The account batch failed to migrate. All changes to the database have been rolled back.

FINISHED

The account batch migrated successfully. All changes to the database have been committed.


About Group Status Flags

AMM sets account groups to a status listed in Table 32-4. You can check an account group's status by running a group_details report. See "Checking Account Group Details".

Table 32-4 Group Status Flags

Status Description

NOT_PROCESSED

The account group has not yet been migrated.

GROUP_DISABLING

All account group members are being disabled in the source database schema. That is, AMM is marking all account group members as invalid to prevent applications from accessing those accounts.

FAILED

AMM did not disable all account group members in the source schema.

GROUP_READY

All account group members were successfully disabled in the source schema. AMM can begin processing batches.

GROUP_IN_PROGRESS

The account group is currently being migrated.

GROUP_FAILED

The account group failed to migrate to the destination schema.

GROUP_FINISHED

The account group migrated successfully.