Applying Custom Migrations for NMS Integrators
The custom migration process allows you to apply custom migrations to the database.
Process Overview
• Custom migrations are entered in an XML file (utility_migrations.xml) that is saved to $NMS_CONFIG.
• Migrations are applied by running nms‑setup or when you run nms‑apply‑migration manually.
• nms‑setup and nms‑apply‑migrations call a script (utility-apply-migrations) that launches utility-migrations.jar, which creates or updates the UTILITY_MIGRATIONS database table and then applies the migrations.
Adding Custom Migrations to the Utility Migrations XML File
The utility_migrations.xml file, which is based on the utility_migrations.xsd schema (found in $NMS_BASE/xml/), has the following structure:
<utility_migration>
<migration>
<base_name>migration1</base_name>
<before>...</before>
</migration>
<migration>
<base_name>migration2</base_name>
<before>...</before>
</migration>
.
.
.
</utility_migration>
• The <base_name> element contains the name of the migration file without any suffix. The migration files are either scripts or *.sql files found in $NMS_HOME/migration/.
• Any number of <migration> elements may be included in utility_migrations.xml.
• The <before> element must have one of the following values:
Running the Migration Scripts
nms‑setup and nms‑apply‑migrations run a utility migration script that checks for the existence of the utility_migration.xml file. When the utility_migrations.xml file is read, the migration information is used to update the UTILITY_MIGRATIONS database table.
All migrations added to the table must actually exist or an error is generated. For any given <base_name> element, the migration system first looks in $NMS_HOME/migrations/scripts for a script with the given base_name found in the xml file. If such a base_name script is found, it will be run when nms‑setup is run. Otherwise, the application will look in $NMS_HOME/migrations/sql for a .sql file with the base_name given in the xml file. If a migration is not found in either directory, an error is generated. All scripts must be executable or the migration will fail to run.
UTILITY_MIGRATIONS Database Table
The migrations found in the $NMS_CONFIG/utility_migrations.xml file are stored in the UTILITY_MIGRATIONS database table, which is defined by the following:
create table utility_migrations (
stamp TIMESTAMP not null,
base_name VARCHAR2(32) unique not null,
before VARCHAR2(1) not null,
applied VARCHAR2(1) not null,
status VARCHAR2(32) not null)
where
• The stamp column is an Oracle TIMESTAMP datatype representing the time when the migration was added to the table. The base_name column should contain the simple file name of the migration without any suffix. The utility-apply-migrations script will look for this sql file in $NMS_HOME/migration/sql. It will also look in $NMS_HOME/migration/scripts for a corresponding file name script, if one exists. If a script exists, it will be executed; otherwise, the sql file is run in instead.
• The before column is set to “T” if a migration is to be applied before product migrations and to “F” if it is to be applied after product migrations.
• The status column will contain the most recent status for a migration. This will usually will be Inserted, Applied, or Failed.
• The applied column is “T” if the migration has been applied to the database. If the applied column is “F”, the migration has not yet been applied to the database.
Note: once a migration has been applied to the database, that migration can no longer be changed in the database.