Home

Example: Full migration

1. Overview
2. From source portal system
3. On target portal environment
4. import-wcm-data error
5. WCM export/import rut
6. CleanUpUsers.xml

Overview

The following procedure is for a full migration of a Web Portal application from a source portal to a target portal. Migration includes pages, wars, jars, WCM content, etc....

From source portal system

1. Create folders for output...
   mkdir c:\scratch\Release01
   mkdir c:\scratch\Release01\wcm
   mkdir c:\scratch\Release01\FOO

2. Export release...
   cd c:\IBM\WebSphere\wp_profile\PortalServer\bin
   xmlaccess.bat -in c:\IBM\WebSphere\PortalServer\doc\xml-samples\ExportRelease.xml -out c:\scratch\Release01\stagev1.xml -url "http://localhost:10039/myapp/config" -user wpsadmin -password foo123

3. Export personalizations
   cd c:\IBM\WebSphere\PortalServer\pzn\prereq.pzn\publish
   c:\IBM\WebSphere\wp_profile\bin\setupCmdLine.bat
   pznload.bat --serverurl "http://localhost:10039/myapp/pznpublish/pznpublishtarget" --targetpath / --username wpsadmin --password foo123 --export --out c:\scratch\Release01\rules.node

4. Export WCM libraries
   cd c:\IBM\WebSphere\wp_profile\ConfigEngine
   ConfigEngine.bat export-wcm-data -DWasPassword=foo123 -DPortalAdminPwd=foo123 -Dexport.allLibraries=true -Dexport.singledirectory=true -Dexport.directory=c:\scratch\Release01\wcm

5. Copy folders in c:\FOO, including....
   • formrules
   • Properties
   • FOODependencies
   • FOOResourceBundles
   • PDFStore

   ...to...

   c:\scratch\Release01\FOO

6. Copy...
   c:\IBM\WebSphere\wp_profile\PortalServer\deployed\archive

   ...to...

   c:\scratch\Release01\archive

   Note that loading archive files into target portal only works if both source and target portal are at the same portal version level. To verify...

   c:\IBM\WebSphere\wp_profile\PortalServer\bin\WPVefooonInfo.bat

   
   

7. Extract latest version of the following ear files...
   cd c:\IBM\WebSphere\wp_profile\bin
   wsadmin.bat -user wpsadmin -password foo123 -c "$AdminApp export MYAPPThemeEAR.ear c:/scratch/Release01/MYAPPThemeEAR.ear"
   wsadmin.bat -user wpsadmin -password foo123 -c "$AdminApp export MYAPPWCMJsp_war c:/scratch/Release01/MYAPPWCMJspEAR.ear"
   wsadmin.bat -user wpsadmin -password foo123 -c "$AdminApp export FOOPlugins c:/scratch/Release01/FOOPlugins.ear"
   wsadmin.bat -user wpsadmin -password foo123 -c "$AdminApp export FOOWebServicesEAR c:/scratch/Release01/FOOWebServicesEAR.ear"

8. Zip up c:\scratch\Release01, then copy to target environment...

   

   We zip file to help prevent packet loss during file transfer to remote system.

On target portal environment

1. Ensure enough heap size is assigned to the Deployment Manager (recommending at least 2 GB) and nodeAgents (recommending at least 512 MB)

2. Tune portal for import.

3. Unzip c:\scratch\Release01.zip

4. Right-click Start button and select...

   Command Prompt (Admin)

   

5. Import WCM data

   1. From WAS console, go to WCM WCMConfigService, and append...
      ,deletemultiplelibraries

      ...to the end of the value for property connect.business.logic.module.

   2. Optional: Add properties...
      connect.businesslogic.module.deletemultiplelibraries.class = com.aptrix.pluto.util.DeleteMultitpleLibrariesModule
      connect.businesslogic.module.deletemultitplelibraries.remoteaccess = true
      connect.businesslogic.module.deletemultitplelibraries.autoload = ralse

   3. Restart portal

   4. Make backup of existing WCM libraries
      cd c:\IBM\WebSphere\wp_profile\ConfigEngine
      ConfigEngine.bat export-wcm-data -DWasPassword=foo123 -DPortalAdminPwd=foo123 -Dexport.allLibraries=true -Dexport.singledirectory=true -Dexport.directory=c:\scratch\Release01\wcm_orig

   5. Delete existing WCM libraries
      cd c:\IBM\WebSphere\wp_profile\ConfigEngine
      ConfigEngine.bat run-wcm-admin-task-delete-libraries -Dlibraries=MYAPP_design,MYAPP_content_en,MYAPP_content_fr -DPortalAdminId=wpsadmin -DPortalAdminPwd=foo123

   6. Import WCM libraries...
      cd c:\IBM\WebSphere\wp_profile\ConfigEngine
      ConfigEngine.bat import-wcm-data -DWasPassword=foo123 -DPortalAdminPwd=foo123 -Dimport.directory=C:\Scratch\Release01\wcm

   7. Reset event logs

6. Verify owner uid is correct in stagev1.xml export file, and change if not. For example, if importing from Syst into Preprod or Prod, change...
   uid=wpsadmin,o=defaultwimfilebasedrealm
   cn=wpsadmin,o=defaultwimfilebasedrealm

   ...to...

   CN=wpsadmin,OU=InternalUsers,DC=ME,DC=FOO
   cn=wpsadmin,ou=roles,dc=me,dc=foo

   To confirm your values are correct, review the values set in wkplc.properties on the target portal system.

7. On all nodes, make a backup of existing archive directory...
   mkdir c:\scratch\Release01\archive_orig
   cd c:\scratch\Release01\archive_orig
   copy c:\IBM\WebSphere\wp_profile\PortalServer\deployed\archive\* c:\scratch\Release01\archive_orig

8. Back up configuration.
   cd c:\scratch\Release01
   c:\IBM\WebSphere\wp_profile\bin\backupConfig backupConfig.zip
   startServer.bat

9. Use xmlaccess to make a backup of target portal release
   cd c:\IBM\WebSphere\wp_profile\PortalServer\bin
   xmlaccess.bat -in c:\IBM\WebSphere\PortalServer\doc\xml-samples\ExportRelease.xml -out c:\scratch\Release01\stagev1_orig.xml -url "http://localhost:10039/myapp/config" -user wpsadmin -password foo123

10. Empty portal

    From primary node, run...

    cd c:\IBM\WebSphere\wp_profile\ConfigEngine
    ConfigEngine.bat empty-portal -DWasPassword=foo123 -DPortalAdminPwd=foo123

    If you get error like:

    [xmlaccess] <request build="wp8001CF16_001_19" type="update" version="8.0.0.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PortalConfig_8.0.0.xsd">
    [xmlaccess] <status element="[cross-page-wire Z10_380CGH02JGNCD0A2SRB43K20K6]" result="failed">
    [xmlaccess] <message >EJPXA0244E: The referenced resource Z5_380CGH02JOC520ACH314PV3002 could not be found in the system.</message>

    To fix, try running again.

11. Run cleanup task on the target portal...
    cd c:\IBM\WebSphere\wp_profile\PortalServer\bin\
    xmlaccess.bat -user wpsadmin -password foo123 -in c:\IBM\WebSphere\PortalServer\doc\xml-samples\Task.xml -out c:\temp\task_result.xml -url http://localhost:10039/myapp/config

12. Deploy ear files.
    c:/scratch/Release01/MYAPPThemeEAR.ear
    scratch/Release01/MYAPPWCMJspEAR.ear
    scratch/Release01/FOOPlugins.ear
    scratch/Release01/FOOWebServicesEAR.ear

13. Copy archive files into place...
    copy c:\scratch\Release01\archive\* c:\IBM\WebSphere\wp_profile\PortalServer\deployed\archive

    We do this because empty-portal removes the deploy/archive files.

14. Verify misc jar files are in place...

    1. On source system, make copies...
       mkdir c:\scratch\misc
       copy C:\IBM\WebSphere\PortalServer\shared\app\FOOFilters.jar c:\scratch\misc
       copy C:\IBM\WebSphere\PortalServer\shared\app\commons-lang-2.5.jar c:\scratch\misc
       copy C:\IBM\WebSphere\PortalServer\shared\app\log4j-1.2.16.jar c:\scratch\misc
       copy C:\IBM\WebSphere\PortalServer\shared\app\nls\config_en.properties c:\scratch\misc
       copy C:\IBM\WebSphere\PortalServer\shared\app\nls\myappRegularExpression_en.properties c:\scratch\misc
       copy C:\IBM\WebSphere\PortalServer\pzn\prereq.pzn\collections\FOOPznServices.jar c:\scratch\misc
       copy C:\IBM\WebSphere\AppServer\lib\ext\FOOJAAS.jar c:\scratch\misc
       copy C:\IBM\WebSphere\AppServer\lib\ext\FOOSecurity.jar c:\scratch\misc

    2. Compress c:\scratch\misc

       

    3. Copy c:\scratch\misc.zip to target system and uncompress in c:\scratch

    4. On target system, copy files into place...

       cd c:\scratch\misc
       copy FOOFilters.jar C:\IBM\WebSphere\PortalServer\shared\app\
       copy commons-lang-2.5.jar C:\IBM\WebSphere\PortalServer\shared\app\
       copy log4j-1.2.16.jar C:\IBM\WebSphere\PortalServer\shared\app\
       copy config_en.properties C:\IBM\WebSphere\PortalServer\shared\app\nls\
       copy myappRegularExpression_en.properties C:\IBM\WebSphere\PortalServer\shared\app\nls\
       copy FOOPznServices.jar C:\IBM\WebSphere\PortalServer\pzn\prereq.pzn\collections\
       copy FOOJAAS.jar C:\IBM\WebSphere\AppServer\lib\ext\
       copy FOOSecurity.jar C:\IBM\WebSphere\AppServer\lib\ext\

15. Set shared library references
    cd c:\IBM\WebSphere\wp_profile\bin
    wsadmin.bat -lang jython -user wpsadmin -password foo123 -f updateLibraryReferences.py

16. Import release
    cd c:\IBM\WebSphere\wp_profile\PortalServer\bin
    xmlaccess.bat -in c:\scratch\Release01\stagev1.xml -url "http://localhost:10039/myapp/config" -user wpsadmin -password foo123

17. Optional: If in a cluster run the ConfigEngine task activate-portlets.
    c:\IBM\WebSphere\wp_profile\ConfigEngine\ConfigEngine.bat activate-portlets

18. Import personalizations
    cd c:\IBM\WebSphere\PortalServer\pzn\prereq.pzn\publish
    c:\IBM\WebSphere\wp_profile\bin\setupCmdLine.bat
    pznload.bat --serverurl "http://localhost:10039/myapp/pznpublish/pznpublishtarget" --targetpath / --username wpsadmin --password foo123 c:\scratch\Release01\rules.node

19. Use BeyondCompare to merge old and new version of...
    • c:FOO\Properties\foo.properties
    • c:FOO\Properties\webservices.properties

20. Copy the following new version of following directories into C:\FOO folders
    • formrules
    • FOODependencies
    • FOOResourceBundles
    • PDFStore

21. If setting values from dmgr, synchronize nodes...
    System administration | Nodes

    ...and do a Full Resynchronize.

22. Restart portal

23. Optional: Before accessing in browser...
    1. Clear your internet browser cache
    2. Close your internet browser

24. Log on to portal and perform smoke test.

25. This site uses web services. If you get SSL errors after logging in, try retrieving the signer cert.

import-wcm-data error

[9/8/15 15:33:35:037 EDT] 00000115 PlutoUtilityM I Utility completed.
[9/8/15 15:34:03:581 EDT] 00000115 PlutoUtilityM I Starting utility: DataModule
[9/8/15 15:34:03:583 EDT] 00000115 PlutoUtilityM I Preserve dates option: False
[9/8/15 15:34:03:583 EDT] 00000115 PlutoUtilityM I Report only mode
[9/8/15 15:34:03:583 EDT] 00000115 PlutoUtilityM I Force unlock option: True
[9/8/15 15:34:03:694 EDT] 00000115 ImportStatusC I RT7547E: [09/08/2015 15:34:03 EDT] Counting the number of files to import.
[9/8/15 15:34:03:833 EDT] 00000115 ImportStatusC I RT7560E: Total files for c:\Scratch\wcm : 1,467.
[9/8/15 15:34:03:833 EDT] 00000115 ImportStatusC I RT7548E: [09/08/2015 15:34:03 EDT] Importing 1467 files.
[9/8/15 15:34:03:839 EDT] 00000115 AbstractImpor I RT7561E: Importing from directory: c:\Scratch\wcm.
[9/8/15 15:34:11:634 EDT] 00000115 ImportStatusC I RT7549E: [09/08/2015 15:34:11 EDT] Imported 200 files (14%).
[9/8/15 15:34:16:508 EDT] 0000010e ServletWrappe I com.ibm.ws.webcontainer.servlet.ServletWrapper init SRVE0242I: [Seedlist_Servlet] [/myapp/seedlist] [SearchSeedlistServletAnonymous]: Initialization successful.
[9/8/15 15:34:28:897 EDT] 00000115 ImportStatusC I RT7549E: [09/08/2015 15:34:28 EDT] Imported 400 files (27%).
[9/8/15 15:34:40:792 EDT] 00000115 ImportStatusC I RT7549E: [09/08/2015 15:34:40 EDT] Imported 600 files (41%).
[9/8/15 15:34:47:375 EDT] 00000115 ImportStatusC I RT7549E: [09/08/2015 15:34:47 EDT] Imported 800 files (55%).
[9/8/15 15:34:54:117 EDT] 00000115 ImportStatusC I RT7549E: [09/08/2015 15:34:54 EDT] Imported 1000 files (68%).
[9/8/15 15:35:00:680 EDT] 00000115 ImportStatusC I RT7549E: [09/08/2015 15:35:00 EDT] Imported 1200 files (82%).
[9/8/15 15:35:09:720 EDT] 00000115 ImportStatusC I RT7549E: [09/08/2015 15:35:09 EDT] Imported 1400 files (95%).
[9/8/15 15:35:11:798 EDT] 00000115 AbstractImpor E SER3008E: An error occurred importing from file: c:\Scratch\wcm\554ee7f5\423dc4e4\b2fc6c13\722a0ed.node. com.ibm.icm.jcr.command.CommandException: RT7027E: Expecting an absolute path. Relative path null was specified. at com.ibm.icm.jcr.command.AbstractImportNodeCommand.importNode(AbstractImportNodeCommand.java:599)

Fix: Files were downloaded/uploaded unzipped. To prevent packet loss during file transfer, archive WCM wcm.zip, then transfer the zip file.

WCM export/import rut

As long as no virtual portals are defined on the source or target systems, we can leave Managed Pages enabled when cloning a WCM database.

• Have a full file system and database backup, and a tested recovery procedure, in case you encounter any problems.

• The release domain of the source and target system should be synchronized prior to cloning the WCM database. This is to ensure that the release domain does not become unsynchronized with the Portal Site library. Different customers do this in different ways. Historically, XMLAccess is the most common, but PAA or synchronization of the Portal Site library do the same thing.

CleanupUsers.xml

However, in certain scenarios in which an LDAP server is changed, the data in the Portal database may no longer be current with the data in the LDAP. Such scenarios cause duplicate users/groups to be created in the Portal database. These duplicates are then used for access control calculations on the Portal server when users log in, while the original user and access control information is considered orphaned.

1. Run CleanupUsers.xml
   cd c:\IBM\WebSphere\wp_profile\PortalServer\bin
   xmlaccess.bat -in c:\IBM\WebSphere\PortalServer\doc\xml-samples\CleanupUsers.xml -out c:\scratch\invalidusersgroups.xml -url "http://localhost:10039/myapp/config" -user wpsadmin -password foo123

   This step generates a set of invalid users and groups in file invalidusersgroups.xml.

2. The decision must be made whether to delete the invalid users and groups using this step or a later step. IBM recommends you leave them in the Portal database temporarily.

   Make the following changes to the file invalidusersgroups.xml in the "request" tag:

   • Set "cleanup-users" to false.
   • Add "migrate-users" and set it to true.

   NOTE: If you see references to users or groups based on the original out-of-the-box user registry (uid=wpsadmin,o=defaultWIMFileBasedRealm), remove the entries from the XML file, or they could potentially cause the next step to fail.

3. Run XMLaccess with invalidusersgroups.xml as the input file:
   xmlaccess.bat -in c:\scratch\invalidusersgroups.xml -out c:\scratch\migration_out.xml -url "http://localhost:10039/myapp/config" -user wpsadmin -password foo123

   At this point, the access control mappings have been migrated to the current external identifiers used by the users and groups in the LDAP. However, there are still orphaned user and group entries in the tables of the Portal databases that should be removed, which is addressed in next step.

4. (Optional but recommended) Run XMLaccess with <wp_root>/doc/xml-samples/ CleanupUsers.xml as input a second time:
   cd c:\IBM\WebSphere\wp_profile\PortalServer\bin
   xmlaccess.bat -in c:\IBM\WebSphere\PortalServer\doc\xml-samples\CleanupUsers.xml -out c:\scratch\removeusersgroups.xml -url "http://localhost:10039/myapp/config" -user wpsadmin -password foo123

   where removeusersgroups.xml is essentially the same as invalidusersgroups.xml which contains the set of orphaned user and group references in the Portal database.

5. (Optional but recommended) Run XMLaccess with removeusersgroups.xml as input to delete the orphaned users and groups:
   xmlaccess.bat -in c:\scratch\removeusersgroups.xml -user wpsadmin -pwd foo123 -url localhost:10039/myapp/config -out c:\scratch\cleanedDB_out.xml

   Ensure that "cleanup-users" is set to invalid in removeusersgroups.xml for this step.

   Check cleanedDB_out.xml for any error messages.

6. Verify the Portal access control settings by logging into the Portal server and confirming that users can view the resources to which they have permission.

Technical Notes:

If you have WCM content, you should run the WCM MemberFixer tool. Before running MemberFixer, complete Steps 4 and 5. Reference the appropriate Portal version Information Center links below depending on the version of the Portal for further details on the MemberFixer tool.

If the system has been configured for VMM property extension or VMM federated database application groups that contain LDAP users, the procedure described above will not clean up the database tables which contain such objects. Please contact IBM support for details on how to perform proper cleanup.

If the LDAP user or group DNs are different after the LDAP change, the above procedure will not work. Contact IBM Support for further details if the user and/or group distinguished names are different before and after the LDAP change.