Introduction
------------
This utility is used to migrate unit test CSE data.  It is designed
to operate on a Solaris/Oracle platform.

The high level flow implemented by the utility is:

   for each test suite
	  delete provisioning data from database
	  load provisioning data into database
	  invoke migration utility
	  extract provisioning data

Usage Scenarios
---------------
Ensure environment is properly set up.  You must run following without 
error before running this utility. 

cd ..../cse/src/BlackBox
. environment
ant databaseSetup

Command line help is available by entering migrateUT:

	  usage: migrateUT {-p plugIn | -l} {-a | test1 ...}
			  -p plugIn - plugIn name to be used for conversion
			  -l - load data only
			  -a - process all test suites in $CSE_UNITTEST_DIR
			  test1 ... - list of test suites with respect to $CSE_UNITTEST_DIR

A normal migration process is:
a/ svn update to get latest
b/ ant databaseSetup to get empty database with new schema
c/ modify database schema to support old and new versions simultaneously
d/ run -l to verify that data will load without errors 
   (search for 'BUILD FAILED', not ORA)
e/ run -p to load & migrate data
f/ ant databaseSetup to get empty database with new schema
g/ run -l to verify that migrated data will load correctly

You can do this one testsuite at a time or in bulk.

If d/ fails, then fix data the data files.
If e/ fails, then fix data files or migration algorithm.
If g/ fails, then restore orginal data files from *.orig and fix data files
or migration algorithm.

Technical Details
-----------------
Assumptions
===========
There are a number of assumptions that need to be true for this system to 
work:

a/ each test suite has a build.xml file.  The format of this file is:
   
   header elements
   <antcall target="Configuration.Default"/>
   <sql>
	   elements to load test data
   </sql>
   other elements

b/ all provisioning data for that test suite is contained in the files:
	- core.sql
	- domain.sql
   These files are located in the test suite directory.  Data for other
   uses, e.g. configuration, must be in separate files which can optionally
   be in the test suite directory.

c/ provisioning data consists of subscribers, subscriptions, devices, domains,
   etc.  It does not include service_definition or configuration data.


Loading Data
============
The utility loads data into the database by extracting the elements to load
test data from build.xml and embedding it into an ant template.  ant is 
then invoked to delete any old data and load the new data.

Migration
=========
The utility is given an argument via -p option which defines the 
migration type.  The migration type is the name of a directory 
in <cmdBase>/plugin, where <cmdBase> is the directory containing the 
migrateUT utility itself.  

At the very least, the migration type directory must contain an 
executable shell script called 'migrate'.  This script is invoked with the 
complete path to the testsuite build.xml file and a migration phase argument.
The latter defines the lifecycle for a migration and is one of 3 values:
  - before - called before data is loaded
  - migrate - called to migrate data
  - after - called after data is migrated

The 'migrate' script returns 0 on success and 1 on failure.   
On failure, the migrate script may leave log files in its own 
directory to help with diagnosis.  The migration 
type directory can also contain other files as required.

If you want to build your own migration plugin, look at some of the existing
scripts as samples.

Dump SQL
========
There is a script and a PL/SQL package that are used to extract the
data from the database into 2 files: core.sql and domain.sql.  These
are then copied back to the test suite using the following algorithm:

  for file in core.sql domain.sql
	if file.orig does not exist in testsuite
	   copy file to file.orig
	copy new file to testsuite

This allows you to run the suite multiple times by restoring 
core.sql and domain.sql files to their original state in the event 
that there are failures that need to be fixed.
