Applying Product Migrations
The Apply Product Migrations process migrates the model of an older Oracle Utilities Network Management System release to that of a new software version. Based on a release level identifier, the migration process determines the differences between the current model and that of a new release. After the installation of a new release of software, and the loading of a copy of your existing production database, you will need to do the following:
• Execute the $NMS_BASE/bin/nms‑setup script.
This script will call another script called nms‑apply‑migrations, which determines the differences between the release level of the software and the model database. This script then determines the required and optional migrations by accounting for differences in the release database requirements.
Manual Product Migrations
If a manual migration is required, the nms‑setup script will stop at that point and alert the user of the required manual migration. When this occurs, please see the corresponding manual migration file in the $NMS_HOME/migration/manual directory for details on what is required for this migration. The files in this directory are named <####>.txt, where <####> is the bug or problem report (PR) number.
The $NMS_CONFIG/migration/data/<project>_config_ready.dat file serves as a “sign-off” document for the Oracle Utilities Network Management System project team. As you determine that a manual migration has been completed (or is not needed for your system), you must add the corresponding bug numbers to the $NMS_CONFIG/migration/data/<project>_config_ready.dat file by entering one bug number per line. Once you have edited this file, you can run $NMS_BASE/bin/nms-install-config to copy it to the $NMS_HOME/migration/data directory or manually copy the file there if you prefer. This signals the migration script that this particular manual migration has been completed. Once the file has been properly copied to $NMS_HOME/migration/data, you need to rerun the nms‑setup script. Continue this process until all manual and automated migrations are executed.
Please note that if the This appendix defines the steps required to migrate a system to a new release. process was followed, the configuration changes that are in $NMS_CONFIG/jconfig will have already been updated. While these changes are listed as requiring manual migrations, they just need to be added to the <project>_config_ready.dat. It is expected that in the future the manual migrations will include only those configuration changes needed to configure a new feature or option.
Note: The bug numbers indicated in the manual migration may not be listed in the Oracle Utilities Network Management System Release Notes supplied with the release. The migrations always refer to an original bug, which is associated with a particular release; any other releases that receive the fix will have a separate bug number (a “copy-bug”). When resolving manual migration issues, always refer back to the text files placed in the $NMS_HOME/migration/manual directory and not the Release Notes HTML associated to that bug fix.
Command Line Options
The nms‑apply‑migrations script can be initiated directly from the command line in order to view some of the things that it will be doing when started from the nms‑setup script. The following table describes all of the command line options for this script.
 
Option
Description
-debug
Displays debug information.
-showme
List all processes that would be executed, but do not actually execute any programs or SQL files.
-needConfig
Displays a list of migrations that are required by a project.
-listMigrations
Displays a list of migrations needed without applying them.
Note: The nms‑apply‑migrations script should not be run without any command-line arguments since that would cause the migrations to actually be executed. The command-line arguments listed above are to be used with the script so that it can be run in a “show only” mode but won't actually do the migrations.
Installing Product Migration Files
The data files that are required for the migration process are installed in the $NMS_HOME/migration/data directory. After making changes to the project-specific $NMS_CONFIG/migration/data/<project>_config_ready.dat file and an optional special $NMS_CONFIG/migration/data/<project>_migration.dat file, run nms‑install‑config script to install them into the $NMS_HOME/migration/data directory.
The Product Migration Process
The nms‑apply‑migrations script determines the database differences by comparing the database release level in the CES_PARAMETERS table with the software release levels found in the software_release_id.dat and software_release_levels.dat files. Based on these differences, it will create a list containing all of the necessary migrations.
The migration process, or nms‑apply‑migrations, finds the necessary migrations in the $NMS_HOME/migration/data/pr_migration.dat file, which contains the list of PRs, releases, patch levels, and configuration types. If there are project-specific migrations, then a optional <project>_pr_migration.dat file is also used.
The pr_migration.dat files resemble the following example:
PR
Release
Patch
Required
Config Required
Script Exists
ConfigType
----
-------
-----
--------
------
------
----------
19254
5.5
3
Y
Y
Y
config_sql
19831
6.0
3
Y
N
Y
schema_sql
 
The following table describes the pr_migration.dat file columns.
Column
Description
PR
Bug number for the migration.
Release
Migration release level, two numbers not including the first digit. For example, release 1.8.1 would be just 8.1 in this field.
Patch
Migration patch level. If the release if 1.8.1.2, then the Patch would be 2.
Required
Whether or not this migration is required for the system to function properly. If set to Y, all projects would be forced to execute this migration when encountered. A value of N means that the migration is optional, and it would be skipped for any projects that do not list it within their <proj>_config_ready.dat file.
Config Required
Whether or not configuration is required by a project for the system to function properly. This value is set to Y whenever a change is made that requires configuration work. For instance, if a new required column is added to a configuration table, the population of this new column properly is the domain of the project engineer, not the developer. Setting this field to Y will flag to all project engineers that this migration requires their attention before the migration can be executed. The specific instructions for configuration migration will be documented in the bug’s Migration section; the manual migration text file located in
$NMS_HOME/migration/manual. Project engineers signify that the configuration has been examined and completed by adding this migration bug to the <proj>_config_ready.dat file.
Script Exists
Indicates whether a script exists for the migration. For example, if a script exists for bug 19254, then there is a script pr19254-migration that performs the migration. Not all migrations involve explicit scripts. As an example, a configuration table change would normally not require a migration. However, if it is important that a new configuration column be properly populated, this must be flagged for project engineers. This is done by adding the bug to pr_migration.dat, setting Config Required to Y and Script Exists to N. Even though there is no migration script, the migration process will not proceed until the project engineer has signified that the configuration is complete by adding the bug to the <proj>_config_ready.dat file.
Config Type
Describes the type of configuration change. Valid values are:
• config_sql - A configuration SQL file has changed.
• schema_sql - A schema SQL file has changed.
• retain_sql - A retain SQL file has changed.
• core_sql - A core (required) data SQL file has changed.
• data - Model (facilities) data is being migrated.
• app_defaults - New or obsolete application default options.
• map_rebuild - The migration script will regenerate map files.
• metafile_rebuild - The script will regenerate all map metafiles.
• service_restart - Services must be restarted.
• environment_restart - All user environments must be restarted.
• post_setup - migration is run during nms-post-setup
Correcting Warnings and Errors
The table below shows the corrections for some possible errors you might receive when running the nms‑apply‑migrations script.
 
Warning
Remedy
WARNING THE FOLLOWING MIGRATIONS NEED CONFIGURATION
PR_NUMBER RELEASE_PATCH
This warning is displayed when migrations requiring manual changes are found. To determine the necessary changes, refer to the corresponding file in the $NMS_HOME/migration/manual directory. After making the manual changes, add the PR number to the $NMS_CONFIG/migration/<project>_config_ready.dat file.
DATABASE RELEASE LEVEL IS GREATER THAN SOURCE RELEASE LEVEL
MIGRATING BACKWARDS NOT SUPPORTED
This error indicates that the schema level of the database is greater than the runtime executables that are being used. You can return to a prior release if you execute the nms‑setup script with the -clean command line option and perform a model build. You should not return to a prior release without running a nms‑setup -clean and a model build, for there may be unresolved problems that could cause system instability.