How To Migrate from DocuShare 2.2 to DocuShare 6.6.1
Caution: Migrating data from DocuShare 2.2 to 4.00.02 can take several hours. You should schedule the migration after business hours. The complete migration path to DocuShare 6.6.1 will most likely take several days.
· Valid support agreement for DocuShare 6.6.1.
· Contact DocuShare Technical Support Desk at 1-800-835-9013 to have your user added to the DocuShare 2.2 Access Group and the DocuShare 4.0.x Access Group on the https://docushare.xerox.com/doug site.
Note: If you do not have a user account on the https://docushare.xerox.com/doug site then you will need to create one before contacting DocuShare Technical Support Desk.
· You will need a server that meets the 4.x & 6.x server requirements to migrate and upgrade to for the first part of the upgrade.
· You will need a server that meets or exceeds the 6.6.1 Server Requirements to upgrade to for the last part of the upgrade.
To Migrate from DocuShare 2.2 to DocuShare 6.6.1:
1. Verify that SP1 & SP2 are installed on your 2.2 Server.
To display the version and Service Packs installed:
From the DocuShare 2.2 server,
Click the About DocuShare link in the lower left corner of the Homepage.
Caution: If SP1 & SP2 are not listed on the page they will need to be installed before proceeding to step 3.
For detailed instructions on how to install Service Packs click the How To Install Service Packs on DocuShare 2.2 link listed at the bottom of the page.
Note: DocuShare 2.2 Service Packs from the following location https://docushare.xerox.com/doug/dsweb/View/Collection-1343.
2. Download the DocuShare 2.2 utilities.
The DocuShare 2.2 Utilities are available at https://docushare.xerox.com/doug/dsweb/View/Collection-12921.
3. Backup the DocuShare 2.2 Server.
Use your standard backup procedure to back up DocuShare 2.2
Note: The following files are required in a minimum site backup:
o Xerox\Docushare\documents directory
o Xerox\Docushare\templates directory
o Xerox\Docushare\metadata directory
4. Install and run the utilities on the DocuShare 2.2 Site.
a. Extract and install the 2.2 Utilities by doing the following:
o Place the .pyc in the DocuShare /commands directory.
o Put the .bat (NT) or script file (has no extension) (Solaris) in the DocuShare /bin directory.
Note: On the Solaris platform you must manually set the environment variable DSHOME to the DocuShare installation directory or from a /bin/csh shell, source the DocuShare/bin/setup_docushare script.
Note: You should be logged in as root.
b. Open a command prompt window and change into the Xerox\Docushare\bin directory
Note: To see a display of the usage of a utility type the use the –h switch.
Usage: check_trash_status [-f] [-v] [-o<outputfile>] <site|trashcan|container handle>
-f Fix trash status of objects different from root container.
-o Message output file.
-v Verbose: show properties of problem items.
When the check_trash_status utility is run on the site or a container handle that has not been deleted, it lists deleted objects.
When the check_trash_status utility is run on the trashcan or a container in the trashcan, it lists objects that have not been deleted.
c. Type check_trash_status -f -o check_trash_status.log -v site and press Enter.
Note: Items in the Trashcan are not copied to the new 4.00.02 server. Trashcan items MUST be Restored to their collections or Expunged prior to migrating data between the servers. The next command will expunge the items in the trashcan.
d. Type dsexpunge all -q and press Enter.
e. Type litterbuster -o litterbuster.log -x and press Enter.
f. Type dscheckup -r -f -o dscheckup_fix.txt and press Enter.
g. Type capture_orphans Collection-xx and press Enter.
h. Where xx is replaced with the Collection handle that you want to send the orphans to if the utility finds any.
i. Type max_proplengths and press Enter.
Note: If any properties are flagged as being too long you need to run the DocuShare 4.x utility to extend the destination server’s property value.
Note: There are 2 ways to perform a Migration from version 2.2 to 4
· Remote migration (Using the Migration Tool) —migrating from a local to a remote system: minimum free disk space is equal or greater than the DS 2.2 directory size.
· Local migration (This is once DocuShare 4 is installed on the same computer as the DocuShare 2.2 installation —migrating on the same local disk: minimum free disk space is 2 times the current DS 2.2 directory size.
5. Install the Migration tool on the DocuShare 2.2 Server (available with DocuShare 4.00.02 full installer package)
Caution: Before starting the migration procedure the DocuShare 2.2 server MUST have Service Pack 1 & 2 installed, ALL Utilities in Step 4 must be ran and the site must be set to Read-Only.
Note: The migration tool does not migrate any customized VDF files to your DS 4.00.02 server. The files must be merged for 4.00.02.
a. Download and extract the DocuShare 4.00.02 installation files on your new server. (the migration tool is part of the Full installer package)
Note: DocuShare 4.00.02 is available at https://docushare.xerox.com/doug/dsweb/View/Collection-1774.
b. Log into your DocuShare 2.2 server as a Windows server administrator.
c. Disable, on the source system, any remote access applications (for example, Remote Terminal Service or PC Anywhere).
d. Launch the installer, enter docushare.exe in the Run window.
e. When the DocuShare Installation Options window displays, select the DocuShare 2.2 Data Migration Tool option.
f. Click Next. The Migration Target screen displays.
g. Enter the target hostname (fully qualified DNS name, such as localhost.xerox.com) and the port parameter. Click Next to continue.
Tech Note: The upgrade target port is the RMI port of the DocuShare 4.0 server (target). The default port number is 1099.
h. When the Install Wizard completes the Migration Tool installation, click Finish to close the installer.
6. Install DocuShare 4.00.02 and have it licensed with at least as many users as the 2.2 site.
Caution: The installation must be done on a server that meets both the 4.00.02 system requirements and the 6.01 System requirements such as Windows 2003
Caution: The server MUST be a new install, not a previously installed 4.00.02 server with metadata.
Caution: The 4.00.02 server MUST be licensed to equal or exceed the number of users for the 2.2 server.
Note: To request a DocuShare 4 license contact DocuShare Licensing at 1-800-735-7749 and/or send an email to the DocuShare Licensing team at email@example.com and request a license string.
Note: For detailed instructions on How To Apply a License String click the How To Apply a New License String / Key in DocuShare link listed at the bottom of the page.
7. Apply Update 7 to the new DocuShare 4.00.02 Server.
Available for download from ttps://docushare.xerox.com/doug/dsweb/View/Collection-4461.
Note: For information on How To Install Updates and Patches click the solution link listed at the bottom of this page.
8. Make a backup of the empty database files for DocuShare 4.00.02 before beginning the migration in case of failure during migration.
The example provided below is for MSDE
Note: Please contact Microsoft for additional information on backing up the database.
From the 4.00.02 Server,
a. Stop the DocuShare service by using either the stop_docushare command line utility or stop DocuShare if you are running it as a service by using the Services Administrative Tool.
b. Stop the MSDE service by using the MSDE Service Manager or by using the Services Administrative Tool.
c. Use your standard backup procedure to back up the Docushare.mdf and the Docushare_log.LDF files that are contained in the --/MSDE/Data/MSSQL$DocuShare/Data directory.
d. Start the Database and DocuShare.
Note: The installation directory for MSDE may or may not be the same on all servers depending on your particular installation.
Note: For detailed information click the How To Backup DocuShare link listed at the bottom of the page.
9. Start the Migration.
The migration tool makes a copy of your content but does not modify the current site. It is recommended to Migrating data requires access to adequate system disk space and virtual memory.
The migration tool copies content and metadata from a DocuShare server (source) to a DocuShare 4.0 server (target). This includes repository contents as well as object property metadata and all user and group accounts
· Remote migration—migrating from a local to a remote system: minimum free disk space is equal or greater than the DS 2.2 directory size.
· Local migration—migrating on the same local disk: minimum free disk space is 2 times the current DS 2.2 directory size. This should no longer be applicable since a customer running DocuShare 2.2 probably does not have it on a Server that would meet minimum specs for DocuShare 4.00.02.
· backup the source server prior to attempting the migration.
To Start the migration:
a. Create a temporary transfer folder (for example, c:\temp).
b. Disable any virus scanning on both the 2.2 server and the 4.00.02 server to improve throughput performance during the migration.
c. Set the source DocuShare server to Read-Only.
d. Change directory to where the DocuShare migration tool is installed (<DSHome>\bin).
e. Enter dsupgrade2 c:\temp in a command window to start the data migration.
f. The source server starts copying the files to the temp folder. Data migration continues by exporting the files to the target server. Progress of the migration is displayed in the command window. A log file is created in the DocuShare 4.0 installed directory, for example <DSHome>\logs.
g. At the completion of data migration, you are prompted to remove the temporary files. Enter yes to remove the files or no to retain the temporary copy.
h. Check the log file for any errors. (<DSHome>\logs)
Note: Normally a database optimization and dsindex_all would be performed at this time; however, because we are moving to DocuShare 6.6.1 the index will not be performed until then.
i. When migration completes, a Migration Status log displays.
j. Verify that all DocuShare 2.2 data has migrated to the DocuShare 4.0 server. Compare the Migration Status log with the About Statistics on the DocuShare 2.2 server.
k. Reboot the server.
10. Backup the DocuShare 4.00.02 Server.
a. Stop DocuShare and the Database Engine.
b. Backup the Xerox\Docushare\documents directory.
Note: The location of the documents directory may vary depending on your installation environment. The location of the documents directory in your environment can be found in Admin Home | Site Management | Directory Paths | Document Repository.
c. Backup the DocuShare database files.
Note: The default DocuShare database files in SQL are called docushare.mdf and docushare_log.ldf.
Note: Verify backup file sizes for both the documents directory and database files to ensure that your backup file sizes match the original size.
d. Restart the Database only.
Note: For detailed information click the How To Backup DocuShare link listed at the bottom of the page.
11. Upgrade to 6.01
a. Log into the server as a Windows server administrator.
Note: Download DocuShare 6.01 build 222 as well as Patch 4 from https://docushare.xerox.com/doug/dsweb/View/Collection-6195
b. Stop DocuShare.
Tech Note: For Microsoft SQL server databases, full text search must be enabled. Run exec sp_fulltext_database enable on the Microsoft SQL server to enable this feature.
c. Exit all Windows applications before starting the DocuShare Installer Setup.
d. Select docushare.exe in the Run window.
e. Click Install DocuShare on the DocuShare Install Menu to begin the installation.
f. The installation program uses Java to install the product. It takes a few minutes to unpack and install the Java files. Click Next to start the DocuShare installation and follow the onscreen instructions.
g. When the DocuShare Installation options window displays, select the option to install DocuShare.
h. Click Next and follow the onscreen instructions.
Note: Whether the installer locates an installed DocuShare instance or that you provide an installed DocuShare path, the installer determines the version installed and provides either the option to upgrade or reinstall.
i. When the Upgrade Option window displays, click Upgrade.
j. Follow the onscreen instructions to continue the upgrade. During the upgrade process, the DocuShare upgrade utility backs up the appropriate system server configuration and data.
k. When the installer completes the DocuShare upgrade, click Finish to close the installer.
Caution: If you do not start DocuShare you can proceed to the step n or if you choose to start DocuShare you will be required to license it before continuing to upgrade to the next version continue with step l.
Note: DocuShare upgrade, installation and upgrade activity is recorded in the DocuShareInstallLog.txt file located in the DocuShare home directory.
Optional: Reboot the system if you selected to run DocuShare as a service, otherwise enter the command <DSHome>\bin\start_docushare in a Command Prompt window to start DocuShare; or in the Control Panel, open the Services application to select and start DocuShare. To complete your DocuShare server upgrade, a new license is required for your DocuShare site.
Note: To request a DocuShare 6 license contact DocuShare Licensing at 1-800-735-7749 and/or send an email to the DocuShare Licensing team at firstname.lastname@example.org and request a license string.
l. Stop DocuShare.
m. Install Update 3 and Patch 51 for DocuShare 6.01 available on our DoUG site:
n. Make another backup of the DocuShare Database and Documents now that it has been upgraded to version 6.01
Note: For information on How To Install Updates and Patches click the solution link listed a the bottom of this page.
12. Upgrade to 6.6.1 Prerequisites
a. Complete the following steps on the DocuShare 6.01 Server before upgrading
· Clear Event Queues
o Note: For detailed information click the How To Clear the Event Queue link listed at the bottom of the page.
o Warning: All events in the queue from 6.0.1 or earlier will be lost during an upgrade. Events in queue from 6.6.x may be corrupted during the upgrade. It is very important that you clear the event queues before upgrading.
· Restrict access to the server by setting the Site Access policy to Administrator. This will prevent additional users from accessing the site.
o To Restrict Site Access:
a) Log into DocuShare as admin and go to Admin Home.
b) Go to Site Management l Access Policies.
c) Set the Site Access Authority to Administrator. Click Apply.
d) Allow all users adequate time to complete any changes and log off.
e) Stop any automated or programmatically generated activities, especially ones that use the Content Intake Manager, Content Rules, or Scan-to-DocuShare services.
b. Stop DocuShare. (if not already stopped)
13. Verify the Bucket Structure
Warning: This step is very important, please verify all the information below before proceeding with the backup and restore procedures.
From the Old DocuShare Server,
a. Open Windows Explorer.
b. Navigate the folder structure into the <dshome>\config directory.
Where <dshome> is replaced with the installation directory for DocuShare. Depending on your installation environment the path may vary. The default installation path is C:\Xerox\Docushare.
c. Open the ContentStore.properties file a text editor such as Notepad.
d. Look for an entry in the file called NumberOfDirectories= it will have a value of 64 or 512, this is very important, make a note of this value.
14. Backup the DocuShare 6.01 Sever.
Repeat steps 10a to 10d.
15. Uninstall DocuShare 6.01.
16. On a server that meets or exceeds the System Requirements. (The new Server must be 64 bit.)
Note: Before re-installing DocuShare fresh, go to http://docushare.xerox.com/products/systemreqs/en/ for the latest system requirements.
a. Move a copy of the DocuShare documents directory to the new server or destination.
b. Move a copy of the DocuShare database files to the new Database Server and verify that the copy of the database is connected, running and available,
Note: If you are using a New Microsoft SQL Server database, run exec sp_fulltext_database enable on the server to enable full text search.
c. Launch the DocuShare software install Wizard by doing one of the following:
o If you are installing from a product media: Insert the DocuShare media into the server drive. If the installer does not open automatically, open the media, locate and double-click setup.bat.
o If you downloaded DocuShare from the web: Download the file to a temporary directory on your server and unzip the file. Open the file, locate and double-click docushare.exe.
Note: If you want the installer to save all configuration and upgrade data, start the upgrade in a command prompt window by entering the command line: docushare.exe -P
Be patient; it takes several minutes for the system to load and start the installer.
d. Follow the onscreen instructions; when the Content Store field is displayed point to the copy of the documents directory.
e. Follow the onscreen instructions until you have selected the database.
f. When the Database Configuration Wizard window displays point to the copy of the database.
g. Follow onscreen instructions.
h. During the Installation, The DocuShare Installation Wizard window will pop up and state that The installation wizard has found the existing DocuShare data in the database remove? Select No.
i. The installer will then proceed to upgrade the target database.
j. When the upgrade successfully completes, click Finish to close the installer.
k. Reboot the server.
After the server restarts, if you did not set DocuShare to run as an autostart service, do one of the following:
· Enter <DSHome>\bin\start_docushare in a command prompt window to start DocuShare.
· In the Administrative Tool, in the Services application, select and start the DocuShare service.
DocuShare initial startup automatically updates the search indexes; allow five minutes before attempting to connect to the site through a browser.
Note: If your DocuShare site uses LDAP over a secure SSL channel, you need to import the SSL certificate into the newly installed dstrust store. Instructions for importing the LDAP SSL Certificate are in the LDAP Active Directory Guide that is located on the Help page of your DocuShare site.
Note: The DocuShare Installer stops the IIS service during the upgrade and restarts it at completion. If the installer does not restart the IIS service, open a command prompt window and enter: net start w3svc.
17. Change the bucket Structure.
a. Stop DocuShare.
b. Open Windows Explorer.
c. Navigate the folder structure into the <dshome>\config directory.
d. Open the ContentStore.xml file in a text editor such as Notepad.
e. Look for an entry in the file called <NumberOfBuckets>512</NumberOfBuckets> edit this value to match the 64 or 512 value that was on your old server.
f. Save the changes to the file.
18. Apply a License Key to Enable DocuShare.
Note: To request a DocuShare 6.6.1 license contact DocuShare Licensing at 1-800-735-7749 and/or send an email to the DocuShare Licensing team at email@example.com and request a license string.
19. Complete the following steps after upgrade to DocuShare 6.6.1
a. Install any Patches or Updates.
Note: For detailed instructions on how to install updates and patches see the How To Install Updates and Patches solution link listed at the bottom of the page.
b. Recommended for performance improvement but not required: Optimize the database
Note: For detailed instructions on How To Optimize the Database refer to the Optimization solution the links listed at the bottom of the page.
c. Enable User Access – Restore Site Access Policy to User or Guest. Enable Read Write mode.
i. Log into DocuShare as admin and go to Admin Home.
ii. Go to Site Management l Access Policies.
iii. Set the Site Access Authority to User or Guest (depending on your site requirements). Click Apply.
iv. Go to Site Management l Site Operations and change the System Mode to ReadWrite. Click Apply.
20. Once Upgrade to DocuShare 6.6.1 is Complete perform the following steps.
Note: Make sure the site is licensed and then perform the procedure below.
a. Stop DocuShare.
b. Make another backup of the Docushare Database and Documents now that it has been upgraded to version 6.01
c. In a command prompt window, run <DSHome>\bin\idoltool -s resetserver all y.
Where <DSHome> is the installation directory for DocuShare. The default installation path is C:\Xerox\Docushare. Depending on your installation environment this path may vary.
Caution: The idoltool -s resetserver all y command clears the IDOL search indexes. This command only should be run immediately before running dsindex index_all.
d. Optional: To increase the allocation of available memory for IDOL on 64-bit Windows servers, run the appropriate idolsetup command according to the amount of RAM on the server.
· 4–8 GB RAM: <DSHome>\bin\idolsetup.bat idol_default.config
· 8–16 GB RAM: <DSHome>\bin\idolsetup.bat idol_medium.config
· 16–32 GB RAM: <DSHome>\bin\idolsetup.bat idol_large.config
· 32+ GB RAM: <DSHome>\bin\idolsetup.bat idol_unlimited.config
Note: At least 6 GB of RAM is recommended on a 64-bit Windows server.
d. Start DocuShare.
e. Run <DSHome>\bin\dsindex index_all.
f. Review the auto_recover_report.log file written to <DSHome>\bin directory.
g. Run <DSHome>\bin\verifyIndex.bat to verify that the documents in the repository have been
h. If DocuShare was configured for LDAP, continue with the following steps. If your site does not use LDAP, you are finished with the procedure.
i. Log into DocuShare as admin and go to Admin Home.
j. From the Administration menu, click Account Management | LDAP Accounts | Bind Group.
k. On the Bind Group page, set the Keywords LDAP Attribute to cn. Click Apply.
l. On the same Bind Group page, remove the Keywords LDAP Attribute entry. Click Apply.
Note: These last two steps invoke a schema update to replace incorrect schema information with up-to-date attribute values from the LDAP server.
Solution Updated: September 12th, 2012
Solution ID: 1110