=========================================================================
    IBM Security Access Manager for Enterprise Single Sign-On (ISAMESSO)
                 User Domain Migration Script
 =========================================================================
 
	Release date 		: 10-Aug-2012
	Script version 		: 1.0.1
	Target IMS version 	: 8.1.x / 8.2.x
	Target Database		: Ms SQL Server 2005/2008

	User domain migration script helps migrate IMS registered user from
 one to another domain together with optional AD GUID and UPN updates. 
 There are a few assumptions made in the script as following.

	Before performing migration, please make sure that :
	
	- New domain is configured in ISAMESSO.
	
	- Target user accounts has been migrated to new domain in enterprise directory.
	
	- Please make sure the older user domain account is no longer active in enterprise 
	  directory to prevent user from re-register in ISAMESSO.

	- No smart card solution has been deployed in ISAMESSO.
	

 1. Creating the stored procedure

	Create this stored procedure in the ISAMESSO schema.
	
	Make sure the database login account that you use in the following tasks has: 
	 * Current schema set to ISAMESSO schema. 
         * Privileges to 
	   - create,drop,execute on stored procedure
	   - select,insert,delete,update on ISAMESSO database tables.


	1.1 Using Microsoft SQL Server Management Studio
	-------------------------------------------------
	
	There are TWO scripts need to be created.
		- sp_base_updEntIdDomainUpnGuid.sql
		- sp_migrateUserDomain.sql
		
	The sequence of the script creation is important as 'sp_migrateUserDomain.sql' 
	depends on 'sp_base_updEntIdDomainUpnGuid.sql'. 

	1.1.1 Open the script "sp_base_updEntIdDomainUpnGuid.sql"
	      In the Microsoft SQL Server Management Studio, Select "File > Open". 
	      Browse to the script "sp_base_updEntIdDomainUpnGuid.sql" and open it. 

	1.1.2 Replace <TARGET DATABASE NAME>, <ISAMESSO SCHEMA OWNER> and Insert the 
	      following command at the first line in "sp_base_updEntIdDomainUpnGuid.sql"
		  ----------------------------
		  USE <TARGET DATABASE NAME>
		  GO
		  EXECUTE AS USER = '<ISAMESSO SCHEMA OWNER>';
		  GO
		  ----------------------------
	1.1.3 Execute the script and make sure "Command(s) completed successfully." is displayed.
	
	1.1.4 Repeat step 1.1.1 to 1.1.3 for 'sp_migrateUserDomain.sql' script creation.
		  
		  
 2. Verifying the creation of a stored procedure
	
	Once the stored procedure is created successfully, execute the following 
	command to verify the script creation:
	
	sp_migrateUserDomain 'ABOUT', '', '', '', NULL, NULL
	
	You must get the similar output as the following if the script is created successfully.
	-----------------------------------------------------
	- ISAMESSO User Domain Migration Script             -
	-   - Script Name      : sp_migrateUserDomain       -
	-   - Script Version   : 1.0.1                      -
	-   - Database Name    : IMS_DB                     -
	-   - Schema Name 	   : IMS_SCHEMA                 -
	-   - Database Version : Microsoft SQL Server 2005  - 
	------------------------------------------------------
	
 3. Using the maintenance script

	  * The database account that is used has the following privileges:
	      - Select, insert, delete, update data in the ISAMESSO schema
	      - Execute stored procedure 
	 
	Maintenance Script Syntax: 
	
	sp_migrateUserDomain '<mode>', '<user id>', '<current user domain>', '<new user domain>', '<new AD GUID>', '<new upn>'
	
	where:
	
 		<mode> - Mandatory, text, case sensitive 
 				- 'ABOUT' display script information
 				- 'HELP' display script syntax and example
 				- 'UPDATE' to perform actual rename
 				- 'SIMULATE' to check on the target enterprise user id without performing actual migration 
 					
		<user id> 	- Mandatory, text, case sensitive
         			- Target user enterprise ID
 
 		<current user domain> 	- Mandatory, text, case sensitive
	           					- current user domain
 
 		<new user domain> 	- Mandatory, text, case sensitive
	           				- new domain to be migrated
 
 		<new AD GUID> 	- Optional, text, case sensitive in '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}' format
			           		- Applicable for Active Directory only
	    		       		- Enter 'NULL' if not applicable or value remain unchanged
	           				- New active directory user account objectGUID value
 
 		<new upn> 	- Optional, text, case sensitive
  					- Enter 'NULL' if not applicable or value remain unchanged

	
 4. Examples

	4.1 Simulate user 'ims001' domain migration with UPN & AD GUID changes from 'current.domain.com' to 'new.domain.com' 
		without performing actual operation
		
		sp_migrateUserDomain 'SIMULATE','ims001', 'current.domain.com', 'new.domain.com', 'ims001@new.domain.com', '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}'

	4.2 Simulate user 'ims001' domain migration from 'current.domain.com' to 'new.domain.com' without performing actual operation'
	
		sp_migrateUserDomain 'SIMULATE','ims001', 'ims002','current.domain.com', NULL, NULL


	4.3 Migrate user 'ims001' from 'current.domain.com' to 'new.domain.com', update UPN to 'ims001@new.domain.com' and AD GUID 
		to '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}'
		
		sp_migrateUserDomain 'UPDATE','ims001', 'current.domain.com', 'new.domain.com', 'ims001@new.domain.com', '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}'


	4.4 Migrate user 'ims001' from 'current.domain.com' to 'new.domain.com' without update UPN & AD GUID
	
		sp_migrateUserDomain 'UPDATE','ims001', 'ims002','current.domain.com', NULL, NULL