This chapter describes how to install Oracle Communications Billing and Revenue Management (BRM) Conversion Manager.
Before you read this document, you should be familiar with how Conversion Manager works. See "Understanding Conversion Manager".
Note:
Conversion Manager is an optional feature that requires a separate license.Conversion Manager is available for the Solaris, HP-UX IA64, AIX, and Linux operating systems and for the Oracle database.
Before installing Conversion Manager, you must install:
Third-Party software, which includes the libraries and JRE required for installing BRM components. See "Installing the Third-Party Software" in BRM Installation Guide.
BRM. See "Putting Together Your BRM System" in BRM Installation Guide.
Oracle 10g, Oracle 11g, or Oracle 12c.
libocijdbc11.so. Conversion Manager requires the use of this OCI Instant JDBC Library.
You need the following information about your existing BRM system during the Conversion Manager installation:
Database alias name of the staged database.
Database port and number for the staged database.
Database user name and password for the staged database.
Database alias name of the primary database schema.
Database port and number for the primary database schema.
Database user name and password for the primary database schema.
Note:
If you have already installed the product, features that are already installed cannot be reinstalled without uninstalling them first. To reinstall a feature, uninstall it and then install it again.To install Conversion Manager:
Download the software to a temporary directory (temp_dir).
Important:
If you download to a Windows workstation, use FTP to copy the .bin file to a temporary directory on your UNIX server.
You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid ”Out of Memory” error messages in the log file. For more information, see "Increasing Heap Size to Avoid ”Out of Memory” Error Messages" in BRM Installation Guide.
Go to the directory where you installed the Third-Party package and source the source.me file.
Note:
You must source the source.me file to proceed with installation, otherwise ”suitable JVM not found” and other error messages appear.Bash shell:
source source.me.sh
C shell:
source source.me.csh
Go to temp_dir and enter this command:
7.5.0_ConversionMgr_platform_opt.bin
where platform is the operating system name.
Note:
You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.Follow the instructions displayed during installation. The default installation directory for Conversion Manager is /opt/portal/7.5.
Note:
The installation program does not prompt you for the installation directory if BRM or Conversion Manager is already installed on the computer and automatically installs the package at the BRM_Home location. BRM_Home is the directory in which you installed the BRM software.Go to the directory where you installed the Conversion Manager package and source the source.me file:
Bash shell:
source source.me.sh
C shell:
source source.me.csh
Go to the BRM_Home/setup directory and run the pin_setup script.
Note:
The pin_setup script starts all required BRM processes.Your Conversion Manager installation is now complete.
You use the pin_cmt utility to migrate the data. To configure performance, log file, and other settings for this utility, edit the Infranet.properties file in BRM_Home/apps/cmt.
Note:
Many of the entries in the Infranet.properties file include default settings that are applicable for testing your data mapping; for example, the number of threads that the pin_cmt utility uses. You can change the settings when you load data into the production system.In addition, you need to edit the pin.conf file for the cmt_mta_cycle_fees utility. This utility is run automatically by the pin_cmt utility to apply cycle fees. The pin.conf file is in BRM_Home/apps/cmt. It includes the standard connection parameters and multithreaded application (MTA) performance setting. You can also specify to not apply cycle fees to accounts.
See "Applying Cycle Fees to Deployed Accounts".
To ensure that the pin_cmt utility finds all the necessary JAR files, include them in the pin_cmt file, in the line that invokes Java. The format is:
BRM_Home/jre/bin/java -Dfile.encoding=utf-8 -cp "jar_A:jar_B:jar_C:jar_D" com.portal.cmt.Cmt $1 $2 $3 $4 $5 $6 $7 $8 $9
where jar_A:jar_B:jar_C:jar_D is the list of Java class JAR files. Oracle library references are appended at the end.
Include all entries on one line with no line breaks. Separate JAR entries with a colon. Do not include any spaces in the list of JAR files. The number of elements is limited only by command-line length (approximately 8 kilobytes on most machines).
The following shows an example:
BRM_Home/jre/bin/java -Dfile.encoding=utf-8 -cp "BRM_Home/apps/cmt/cmt.jar:BRM_Home/jars/xercesImpl.jar:BRM_Home/jars/xmlParserAPIs.jar:BRM_Home/jars/pcm.jar:BRM_Home/jars/pcmext.jar:BRM_Home/apps/cmt" com.portal.cmt.Cmt $1 $2 $3 $4 $5 $6 $7 $8 $9
When you import data that is in finite partitioned classes, you can define the timestamp validation mode that is encoded in the POID of a finite partitioned class. You provide the timestamp validation mode as the value for the infranet.cmt.timestampvalidation entry in the Infranet.properties file for use by Conversion Manager.
Table 22-1 lists the valid entries for infranet.cmt.timestampvalidation.
Table 22-1 Valid Modes for Timestamp Validation
| Input Value | Timestamp Validation Mode |
|---|---|
|
0 |
No timestamp validations are performed. If an entry is provided in created_t, that creation time is used for a finite partitioned class. Otherwise, the current system time is used for a finite partitioned class. |
|
1 |
The created_t entry is mandatory for any finite partitioned class. It should be provided in the input XML file containing the legacy data to be imported. If created_t is not provided, Conversion Manager generates an error. This is the default value for Infranet.cmt.timestampvalidation. |
|
2 |
The default time is used for the POID encoding. If created_t is provided for any finite partitioned class, Conversion Manager generates an error. |
To add the infranet.cmt.timestampvalidation entry to the Infranet.properties file:
Open the BRM_Home/apps/cmt/Infranet.properties file in a text editor.
Add the following entry. Provide the required value for n. See Table 22-1.
infranet.cmt.timestampvalidation = n
Note:
If you provide an invalid input for infranet.cmt.timestampvalidation, BRM replaces that value with the default value (1).Save and close the Infranet.properties file.
When you import data, the data is migrated to your production database, but it is not accessible to normal BRM processes until it is deployed. To view the data, you need to configure one or more Oracle Data Manager (DMs) as scoped DMs. A scoped DM can view accounts according to their stage ID. You can configure multiple scoped DMs, one for each staging area.
In addition to configuring scoped DMs, you also need to configure the production Oracle DM to support DM scoping.
A BRM system that includes scoped DMs is called a scoped system.
To configure a scoped system:
Run the pin_convert_nonunique.sql script in BRM_Home/apps/cmt/scripts. This script drops unique constraints for indexes used in account creation.
Note:
By default, the pin_convert_nonunique.pl script uses PINX00 to identify tablespaces for indexes. If you use a name other than PINX00, edit the pin_convert_nonunique.pl script to change PINX00 to your tablespace name.Run the BRM_Home/sys/dd/data/cmt_copy_group_planlists_oracle.sql stored procedure. This procedure duplicates the /group/plan_list object with the staged database number, which enables you to create accounts by using Customer Center.
The stored procedure uses the following parameters:
Database number; for example, 5
Return code (number)
Return message (varchar2(100))
The following shows a sample call using PL/SQL:
declare p_return_code number; p_return_mesg varchar2(100); begin CMT_COPY_GROUP_PLANLISTS_ORACLE(5,p_return_code,p_return_mesg); end;
Create a pin.conf file for each scoped Oracle DM. To do so, edit the Oracle DM pin.conf file in BRM_Home/sys/dm_oracle.
Edit the following entries:
Set the scoped_system entry to 1. This enables database scoping.
Set the production_system entry to 0. This identifies the DM as a scoped DM.
Set the staging_db_number entry to the stage ID used for importing data. If you use a multischema system, the stage ID must be larger than the largest schema database number.
Include the table names for the data you are importing in the scoped_exception_tables entry.
For example, a scoped DM for stage ID 11 has the following entries:
- dm scoped_system 1 - dm production_system 0 - dm staging_db_number 11 - dm scoped_exception_tables channel_event_t channel_t config_t data_t deal_t plan_t product_t rate_plan_selector_t rate_plan_t rate_t search_t zonemap_t
Repeat the DM pin.conf configuration for each scoped DM, using a different stage ID for each one.
Configure the production Oracle DM by editing the following entries:
Set the scoped_system entry to 1.
Set the production_system entry to 1. This identifies the DM as the production DM.
Include the table names for the data you are importing in the scoped_exception_tables entry.
The configuration for the production system looks like this:
- dm scoped_system 1 - dm production_system 1 - dm scoped_exception_tables channel_event_t channel_t config_t data_t deal_t plan_t product_t rate_plan_selector_t rate_plan_t rate_t search_t zonemap_t
Start the scoped DMs.
Create a root account for each stage ID:
Start the scoped Oracle DMs.
Open the load_pin_acct script in BRM_Home/apps/cmt/scripts.
Edit the first line of the script to point to a valid Perl path. For example:
/opt/portal/ThirdParty/perl/5.8.0/bin
Edit the $dm_port entry to point to the Oracle DM port number. For example:
$dm_port = 22251
Make sure the $db_no entry points to the production database. For example, if the production database number is 0.0.0.1, and the staged database number is 0.0.0.11, use the following entry:
$db_no = 0.0.0.1
Save and close the file.
Run the load_pin_acct script using the following command:
load_pin_acct -I pin_init_acct
Note:
The input flist used when the root account is created still refers to the production database number because the staging DM translates it to the staging database number.Stop and restart all Connection Managers and Oracle DMs used for accessing the staged data.
If you are migrating data to a multischema system, edit the entries shown in Table 22-2 in the BRM_Home/apps/cmt/Infranet.properties file:
Table 22-2 Infranet.properties File Entries to Enable Multischema Loading
| Entry | Description |
|---|---|
|
infranet.cmt.deploy.multidb |
Enables or disables data migration in a multischema system. Enter true or false. |
|
infranet.cmt.primarydbname |
Specifies the database schema name (for example, pindb1). |
|
infranet.cmt.primarydbuserid |
Specifies the schema login name. |
|
infranet.cmt.primarydbpasswd |
Specifies the schema login password. |
|
infranet.cmt.primarydbnumber |
Specifies the database number for the primary schema (for example, 0.0.0.2). |
The pin_cmt utility can validate the input files to ensure that the data has the correct structure. However, this decreases performance. If you validate the XML prior to loading the data, you can leave validation disabled.
Tip:
You can test the data mapping by enabling validation when you migrate data to a test database. You can also test the data mapping by using the Conversion Manager XSD file with an online XML validator or third-party tool.To enable or disable XML validation, edit the infranet.cmt.preprocess.validation entry in the Infranet.properties file:
infranet.cmt.preprocess.validation = true
Edit the following entries in the Infranet.properties file to match your typical account configuration:
Use the infranet.cmt.avgnoofservices entry to specify the average number of services that each account owns. This entry reserves Portal object IDs (POIDs) for the objects that will be created by the pin_cmt utility. The default is 5.
Use the infranet.cmt.avgnoofdevices entry to specify the average number of devices that each account owns. This entry reserves POIDs for the objects that will be created by the pin_cmt utility. The default is 2.
Use the infranet.cmt.noofrecords entry to specify the average number of account records in each input XML data file.
Use the infranet.cmt.dbnumber entry to set the staged database number (for example, 0.0.0.12). Use the infranet.cmt.dbname, infranet.cmt.userid, and infranet.cmt.passwd entries for the rest of the staged database information.
Use the infranet.cmt.targetdbnumber entry to set the target database.
Note:
If an account owns more or fewer services or devices than the numbers you specify, the objects are still loaded.When accounts are imported, balance groups are created for the accounts.
You can specify which credit limit profile is assigned to each balance group in the following ways:
You can specify the default credit limit profile by editing the infranet.cmt.creditprofile entry in the Infranet.properties file:
infranet.cmt.creditprofile = IndexID
Each credit limit profile is stored in a PIN_FLD_PROFILES array in the /config/credit_profile object. Replace IndexID with the index ID of the appropriate PIN_FLD_PROFILES array. In this example, you would replace IndexID with 3:
0 PIN_FLD_PROFILES ARRAY [3] allocated 3, used 3
1 PIN_FLD_CREDIT_FLOOR DECIMAL [0] NULL
1 PIN_FLD_CREDIT_LIMIT DECIMAL [0] 133
1 PIN_FLD_CREDIT_THRESHOLDS INT [0] 0
You can assign a credit limit, credit floor, and credit threshold to each balance group when you run the pin_cmt utility. To do so, add the following XML elements to the input XML file that you import with pin_cmt:
<CrdLmt>
<CrdFlr>
<CrdTrsh>
The values specified in the input XML file take higher precedence than the value of the infranet.cmt.creditprofile entry in the Infranet.properties file.
By default, the pin_cmt utility runs a separate utility, cmt_mta_cycle_fees, to apply cycle fees after deploying accounts. To disable this, edit the infranet.cmt.deploy.opcode entry in the BRM_Home/apps/cmt/Infranet.properties file:
infranet.cmt.deploy.opcode = false
By default, when you migrate new balances to an account that was previously migrated using Conversion Manager, the pin_cmt utility deletes the existing balances on the account and associates only the newly migrated balances to the account.
To migrate new balances to an account without deleting the existing balances:
Open the BRM_Home/apps/cmt/Infranet.properties file in a text editor.
Add the following entry:
infranet.cmt.deleteexistingbalances = false
Save and close the file.
If your BRM implementation uses 31-day billing, configure the following entries in the Infranet.properties file:
infranet.cmt.31daybilling = true
infranet.cmt.31daybilling.forward = true
If the infranet.cmt.31daybilling.forward entry is enabled, BRM performs forward billing if the billing day of month is greater than 28. If it is disabled, BRM performs backward billing.
For more information, see "Using 31-Day Billing" in BRM Configuring and Running Billing.
If your BRM implementation uses delayed billing, configure the following entry in the Infranet.properties file:
infranet.cmt.billingdelay=true
For more information, see "Setting Up Delayed Billing" in BRM Configuring and Running Billing.
Conversion Manager performance depends on the data and features used for a given BRM implementation. Therefore, this documentation includes guidelines, but does not provide specific values for performance-related configuration settings.
Limit the number of accounts in an XML file to 10,000 accounts. Conversion Manager supports XML files with any number of accounts, but limiting the number of accounts enables you to debug the migration in the case of an error message.
When you create the XML files:
Validate the files with the Conversion Manager physical XML schema.
Use the proper tab (\t) and new line (\n).
Do not use spaces.
Make sure all the required tags are present in the XML.
Use multiple instances of the pin_cmt utility to load multiple XML files simultaneously.
For example, you can write a batch/shell script similar to this:
cat >> run.sh << EOF date > start.txt pin_cmt -import -file one.xml 1 & pin_cmt -import -file two.xml 1 & pin_cmt -import -file three.xml 1 & pin_cmt -import -file four.xml 1 & pin_cmt -import -file five.xml 1 & wait date > end.txt EOF
While running the script, measure the CPU load and time taken by the pin_cmt utility for this entire batch. You can then increase the number of pin_cmt instances until the CPU load reaches 90%.
To improve performance, you can use connection pooling with Conversion Manager. Configure the following entries in the Infranet.properties file:
infranet.cmt.minconns
infranet.cmt.maxconns
infranet.cmt.timeout
For example:
infranet.cmt.minconns = 15 infranet.cmt.maxconns = 30 infranet.cmt.timeout = 1000
For more information, see "About Connection Pooling" in BRM System Administrator's Guide.
For test migrations, the default log file settings are set to return troubleshooting information. For better performance, you should change those settings to report less information.
In the BRM_Home/apps/cmt/pin.conf file, change the pin_mta loglevel entry to 1.
In the BRM_Home/apps/cmt/Infranet.properties file, change the infranet.log.level entry to 1.
Migrating data can use a lot of system resources. Performance can depend on:
RAM size
Number of CPUs
Disk quotas
File system usage
After you have validated the XML files and are ready to load data, edit the BRM_Home/apps/cmt/Infranet.properties file to maximize performance.
Turn off XML validation:
infranet.cmt.preprocess.validation = false
Set the following entries to correspond to the amount of data in the XML files. The infranet.cmt.noofrecords entry specifies the number of accounts.
infranet.cmt.noofrecords = 1000 infranet.cmt.avgnoofservices = 5 infranet.cmt.avgnoofdevices = 2
Configure sufficient threads in the preprocess thread pool.
infranet.cmt.preprocess.num_of_threads = 5
The default value is 5, which is the optimal value in most cases.
Make sure there are enough connections in the staging database connection pool:
infranet.cmt.minconns = 15 infranet.cmt.maxconns = 30 infranet.cmt.timeout = 1000
To test your mapping, you can run the pin_cmt utility with the default memory allocation. However, when migrating a production database, you might need to increase the memory allocation to prevent a system hang.
Edit the pin_cmt script to avoid system hangs.
Note:
Depending on your system configuration and load, your settings might be different.JAVA_OPTIONS="-Xms1024m -Xmx2048m" BRM_Home/jre/bin/java $JAVA_OPTIONS -Dfile.encoding=utf-8 –cp "BRM_Home/apps/cmt/cmt.jar:BRM_Home/jars/xercesImpl.jar:BRM_Home/jars/xmlParserAPIs.jar:BRM_Home/jars/pcm.jar:BRM_Home/jars/pcmext.jar:BRM_Home/apps/cmt"com.portal.cmt.Cmt $1 $2 $3 $4 $5 $6 $7 $8 $9
In the BRM_Home/apps/cmt/Infranet.properties file, verify the command line parameters for the SQL*Loader.
infranet.cmt.sqlldr = sqlldr streamsize=2621440 readsize=2621440 columnarrayrows=5000
When you use the flag direct=”true”, make sure the BRM user has DBMS_LOCK permission.
Before you deploy data, edit the following entries in the Conversion Manager pin.conf file. The file is located in BRM_Home/apps/cmt.
Set the log level to 1:
- pin_mta loglevel 1
Specify the appropriate capacity settings for your system; for example:
- pin_mta children 5 - pin_mta per_batch 500 - pin_mta per_step 1000 - pin_mta fetch_size 5000