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 to
create an empty database without error before running this utility. 

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

This will create an empty database.  You then need to load the 
configuration data with:

  sqlplus ..... <misc/config.sql

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, as above, 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 
e/ run -p to load & migrate data
f/ ant databaseSetup, as above, to get empty database with new schema
g1/ run -l to verify that migrated data will load correctly
g2/ run misc/loadAll to simulate simultaneous conformance data load 
	done by nightly conformance.  This will check for ID conflicts.

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 suit has a name that appears at the end of the sql filename,
	e.g. core_base.sql, would be known as 'base' dataset

b/ all provisioning data for that test suite is contained in the files:
	- core_BBB.sql
	- domain_BBB.sql
	- local_auth_context_BBB.sql.tmpl
   These files are located in the directory .../conformance/provisioning.  

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 deleting old provisioning data
and then loading the 2 or 3 files in the dataset.

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 
the name of the testsuite 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 or 3 files: core.sql, domain.sql and
local_auth_context.sql.tmpl.  These are then copied back to the 
test suite using the following algorithm:

  for file in core.sql domain.sql local_auth_context.sql.tmpl
	if file_BBB.orig does not exist in testsuite
	   copy file_BBB to file_BBB.orig
	copy new file to .../conformance/provisioning/file_BBB.orig

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