=========================================================================
    IBM Security Access Manager for Enterprise Single Sign-On (ISAMESSO)
                Enterprise User ID Rename Script
 =========================================================================
 
	Release date 		: 31st July 2012
	Script version 		: 1.0.0
	Target IMS version 	: 8.1.x / 8.2.x
	Target Database		: DB2 v9.7

	Enterprise ID rename script helps rename IMS registered user 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 :

	- Target user accounts has been renamed in enterprise directory.
	

 1. Creating a stored procedure

	Create a stored procedure in the ISAMESSO schema.
	
	Make sure the database login account that uses the following tasks have a
	current schema that points to the ISAMESSO schema and with the following privileges:
	 - Create,drop,execute on a stored procedure
	 - Create,drop,select,insert,delete,update on a session temporary table
	 - Select,insert,delete,update on ISAMESSO database tables.
	 
	There are TWO scripts need to be created.
		- sp_base_updEntIdDomainUpnGuid.sql
		- sp_changeUserEntId.sql	

	The sequence of the script creation is important as 'sp_changeUserEntId.sql' 
	depends on 'sp_base_updEntIdDomainUpnGuid.sql'. 

	Choose either 1.1 or 1.2 steps to create a stored procedure.	

	1.1 Using the DB2 Command Shell
	----------------------------
	1.1.1 Replace <database name>, <user id> and <password> in the following 
		  script and execute it to connect to the target database.
		  
		  db2 connect to <database name> user <user id> using <password>
		  		
	1.1.2 Replace the <script location> and execute the following command.
	
		  db2 -td# -f <script-location>sp_base_updEntIdDomainUpnGuid.sql 
	
	1.1.3 Repeat step 1.1.2 for 'sp_changeUserEntId.sql' script creation.

	
	1.2 Using the DB2 Command Editor UI
	--------------------------------
	1.2.1 Start DB2 control center, select "Tools \ Command Editor" from 
	      the top menu to launch the DB2 command editor. 
	      
	1.2.2 Replace <database name>, <user id>, and <password> in the following 
		  script and execute it to connect to the target database.
		  
		  connect to <database name> user <user id> using <password>
		  
	1.2.3 Select "Selected \ Open" from the top menu and browse to the
	      "sp_base_updEntIdDomainUpnGuid.sql" script location to open it.
	      
	1.2.4 Change the "statement termination character" at the bottom to "#"
	
	1.2.5 Execute the script and make sure the stored procedure is created 
		  successfully.
		  
	1.2.5 Repeat step 1.2.3 to 1.2.5 for 'sp_changeUserEntId.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:
	
	call sp_changeUserEntId ('ABOUT', '', '', '', '')
	
	You must get the similar output as the following if the script is created successfully.
	-----------------------------------------------------
	- ISAMESSO Rename Enterprise ID Script              -
	-   - Script Name      : sp_changeUserEntId         -
	-   - Script Version   : 1.0.0                      -
	-   - Database Name    : IMS_DB                     -
	-   - Schema Name 	   : IMS_SCHEMA                 -
	-   - Database Version : DB2 v9.7.400.501           - 
	------------------------------------------------------	
	
 3. Using the maintenance script

	Before executing the script make sure of the following:
	  * The current schema points to the ISAMESSO schema.
	    To set the current schema to ISAMESSO schema, use the following command:

		set current schema = '<SAMESSO schema name>'

	  * 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: 
	
	call sp_changeUserEntId ('<mode>', '<current user id>', '<new user id>', '<user domain>', '<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 

 		<current user id> - Mandatory, text, case sensitive
	          			  - Target user enterprise ID
	          			  
 		<new user id> 	- Mandatory, text, case sensitive
          		 		- Target user enterprise ID
          		 		
 		<user domain> 	- Mandatory, text, case sensitive
 	      	     		- current user domain
 		<new upn> 	- Mandatory, text, case sensitive
   					- Enter 'NULL' if not applicable or value remain unchanged

	
 4. Examples

 	4.1 Simulate user 'ims001' enterprise ID & UPN changes without performing actual operation
 		call sp_changeUserEntId ('SIMULATE','ims001', 'ims002','current.domain.com', 'ims002@current.domain.com')

	4.2 Simulate user 'ims001' enterprise ID changes without performing actual operation
		call sp_changeUserEntId ('SIMULATE','ims001', 'ims002','current.domain.com', NULL)

	4.3 Rename user 'ims001' from 'current.domain.com' to 'ims002' and update UPN to 'ims002@current.domain.com'
		call sp_changeUserEntId ('UPDATE','ims001', 'ims002','current.domain.com', 'ims002@current.domain.com')
		
	4.4 Rename user 'ims001' from 'current.domain.com' to 'ims002' without update UPN
		call sp_changeUserEntId ('UPDATE','ims001', 'ims002','current.domain.com', NULL	)


5. Known Issue on Access Agent side

	If the user had cached his wallet on the client machine, then first time logon using the new user ID will give an error "You cannot logon to the wallet on this computer because it has been revoked". This is expected. From the second time onwards, login using new user ID will be successful and the user's wallet will be downloaded from the IMS server and the user can choose to cache the wallet locally.