How to migrate DocuShare 7 from one server to another

Note: You must be a Windows Administrator to perform this solution.

Note: This process is for migrating DocuShare only, it does not include the steps for an upgrade.

Before you start

• Review the System Requirements for DocuShare 7 and verify that your Server meets all the requirements. System Requirements are available here: https://www.docushare.com/system-requirements/

   

• If your site is customized, you will need to back up all your customizations, then apply the customizations to the new DocuShare 7 site once migrated to the new server.  

All customizations should be in the <dshome>\amber\templates\local directory. To back them up, copy the contents of the local directory to another location.

• If your DocuShare installation has custom integrations or custom solutions, please notify DocuShare customer support of this so they can advise on the appropriate path to migrate to a new server.

   

• If you are using XPA or eForms contact DocuShare customer support to discuss a migration path that is suitable for your environment.

   

• If using the Scan Cover Sheet functions of DocuShare (Glyphscan) and you change any of the following information DocuShare Server’s IP Address or Hostname, HTTP Protocol, HTTP Port and/or DocuShare Root it may require you delete and re-create all the scan cover pages. The dataglyph that is located on the bottom of a scan cover sheet has information regarding your server’s URL

   

1. Install DocuShare 7 on the new server. Install to the same path as the old server. (For example: Xerox\Docushare). Do not point to the location of the old server’s database or documents directory or the information will be overwritten.

Note: The new DocuShare installation needs to be at the same version, update and patch level as the old one. If needed apply any updates or patches that are required to match the old server.

2. Start and license the new DocuShare 7 site.

Note: DocuShare Licensing can be reached by calling 1-800-735-7749 and/or emailing docushare.licenses@xerox.com. The licensing department will require the version of DocuShare installed on your server and the Host ID of the server. The DocuShare license key will need at least the same number of users as the server had that you will be restoring.

3. Once the new DocuShare 7 Site is licensed, stop the new DocuShare 7 site.

4. Verify the Bucket Structures of the old server and the new server match.

Warning: This step is very important, please verify all the information below before proceeding with the backup and restore procedures.

1. To verify your bucket structure on the old server:

1. Open Windows Explorer
2. Navigate the folder structure into the <dshome>\config directory.

Where< dshome> is replaced with the installation directory for DocuShare.  The default installation directory is C:\Xerox\Docushare.  Depending on your installation environment the path may vary.

3. Open the ContentStore.xml file (in notepad or WordPad).
4. Look for an entry in the file called <NumberOfBuckets>512</NumberOfBuckets> it will have a value of 64 or 512, this is very important, make a note of this value.

2. To verify the new server has the same bucket structure configuration.

1. On the newly installed server, open Windows Explorer.
2. Navigate the folder structure into the <dshome>\config directory.
3. Open the ContentStore.properties file in a text editor such as Notepad.
4. Look for an entry in the file called NumberOfDirectories= edit this value to match the value found in step 4A. Then save the changes.
5. Open the ContentStore.xml in a text editor and look for the entry <NumberOfBuckets>512</NumberOfBuckets> edit this value to match the value that was on your old server. Then save the changes.

Warning: You must modify both the <dshome>\config\ContentStore.properties and the ContentStore.xml files to match the value that was on your old server. 

1. Verify the Access Tracking Values on the Old and New Server match.

Warning: It is very important to check the data retention value matches the old server if you are moving to a new DocuShare server or install because if a customer changed the default value to a higher number of days or infinite days on the old server and does not make the appropriate changes on the new install, it will start purging the access data that is older than 365 days when DocuShare is first starting up on the new server.   Also, in addition to deleting access tracking data (which may be critical for some customers), it may result in database transaction log to get full and bog down DocuShare.

1. On the old server, log into DocuShare as admin.

2. Click Admin Home | Site Management | Access Tracking. The Access Operation Tracking page displays.

3. Scroll to the bottom of the page, check the value in the field labeled Monitor Access Data and Access Data Retention.

Note: There is an internal timer that gets reset every time these values are changed.   The data gets flushed from the Access_Table whenever those values are changed.

Note: The default value on a fresh install is 365 days. 

Examples:

Changing the Access Data Rendition value to 180 days will flush the oldest data at the next check interval which is the value of the Monitor Access Data (default check time is every 1.6 minutes) leaving the desired 180 days’ worth of data.

1. On the new server, make sure the value matches the old server.

    

6. Backup the old DocuShare site.

Use your standard backup procedure to backup DocuShare. See detailed information below on what a backup must contain.

Minimum backup requirements

To keep database information and site information in synch, either stop DocuShare or place the site in Read Only mode before starting a backup. Back up database files and DocuShare directory files during the same backup cycle so there will be no inconsistencies between database information and site information.

You must, at a minimum, back up the Docushare\documents directory and all DocuShare

database files.

The location of the \documents directory varies depending on the site installation environment.

The \documents directory for a site is displayed in the Document Repository field on the Site

Management l Directory Paths Admin UI page.

For sites using SQL databases, the default database files are named Docushare.mdf and

Docushare_log.LDF.

If your site is using the database that was bundled with DocuShare, we recommend that you back

up the entire DocuShare install directory. In this case you must stop both DocuShare and the

database in order to release all necessary files from running processes.

Backup recommendations

To make site file restoration faster and easier, we recommend that you back up the entire Xerox\Docushare install directory. Using this strategy, you back up all site content that is located under the Xerox\Docushare directory, including configuration files and site customization files.

7. Backup the IDOL Index on the old Server(optional).

Note: If you choose to not backup IDOL then you will need to do a dsindex index_all on the new server for search capabilities. Depending on the size on your site doing a dsindex index_all can take a long time to complete.

To perform a manual backup of IDOL Index data

1. Open a command prompt window (Windows) or terminal window (Linux/Solaris)

2. Change into the <dshome>\ bin directory.

3. Run one of the following commands depending on your environment.

• idoltool.bat –s backup <path_to_backup_directory> (Windows)

• idoltool.sh –s backup <path_to_backup_directory> (Linux / Solaris).

Where <path to backup directory> is replaced with the path to the backup folder.  For example, D:\content_backup.

Example (Windows): idoltool.bat –s backup D:\content_backup

Example (Linux/Solaris): idoltool.sh –s backup /content_backup

Note: The backup will need to be run on each content if you are running more than one content. The command line statement will need to be modified if you have more than one content. 

Example (Linux / Solaris):

• For content0: idoltool.sh -s backup /content0_backup0 content0

• For content1: idoltool.sh -s backup /content1_backup0 content1

Example (Windows):

• For content0: idoltool.bat -s backup c:\idolbackup content0

• For content1: idoltool.bat -s backup c:\idolbackup content1

• For content2: idoltool.bat -s backup c:\idolbackup content2

1. After performing a backup, the following information will be displayed in the log files:

• If you are running one Content engine.

The <dshome>/logs/idoltool.log will display the following:

20110927 13:16:39 -     Submitted DREBACKUP, jobid = 19

20110927 13:16:43 -   IdolAdmin.waitForJobCompletion: id = 19: Finished; documents processed: 0...

20110927 13:16:43 -   backup: Done.

• If you are running multiple Content engines, the logs will be named slightly different and will be found in the following locations.

For Content0: <dshome>\IDOLServer\content0

• application.log
• index.log

For Content1: <dshome>\IDOLServer\content1

• application.log
• index.log

Example of the <dshome>\IDOLServer\IDOL\logs\content_application.log:

21/10/2013 13:36:40 [1] Backing up database into existing directory 'C:\BackupIDOL'

21/10/2013 13:36:40 [1] Backing up "Main" files into directory 'C:\BackupIDOL/main'

21/10/2013 13:36:40 [1] Backing up "Status" files into directory 'C:\BackupIDOL/status'

21/10/2013 13:36:40 [1] Backing up "Dynterm" files into directory 'C:\BackupIDOL/dynterm'

21/10/2013 13:36:43 [1] Backing up "Nodetable" files into directory 'C:\BackupIDOL/nodetable'

21/10/2013 13:36:44 [1] Backing up "Refindex" files into directory 'C:\BackupIDOL/refindex'

21/10/2013 13:36:44 [1] Backing up "Numeric" files into directory 'C:\BackupIDOL/numeric'

21/10/2013 13:36:44 [1] Backing up "BitField" files into directory 'C:\BackupIDOL/bitfield'

21/10/2013 13:36:44 [1] Backing up "Secindex" files into directory 'C:\BackupIDOL/secindex'

21/10/2013 13:36:44 [1] Backing up "TagIndex" files into directory 'C:\BackupIDOL/tagindex'

21/10/2013 13:36:44 [1] Backing up "SortField" files into directory 'C:\BackupIDOL/sortfield'

21/10/2013 13:36:44 [1] Backing up "IndexQueue" files into directory 'C:\BackupIDOL/indexqueue'

21/10/2013 13:36:44 [1] Backup Complete.

Example of the <dshome>\IDOLServer\IDOL\logs\content_index.log:

27/09/2011 13:16:39 [0] Index connection granted to: 127.0.0.1

27/09/2011 13:16:39 [0] Index Queue Command: /DREBACKUP?/Docushare/content0backup

27/09/2011 13:16:39 [1] Index Queue Command: DREBACKUP?/Docushare/content0backup

27/09/2011 13:16:42 [1] Index command finished. Took 2.88 s

8. On the New DocuShare Server use your standard restore procedure to restore the backed up DocuShare Database.

9. Use your standard restore procedure to restore the content store repository (Xerox\Docushare\documents directory).

Note: Do not overwrite or delete the guid.txt file located in the documents directory.

10. If the location of the database or the documents directory you restored to the new server are in a different location than what the initial installation points to, you will need run dssetup from the Command Prompt in the <dshome>\bin directory and point to the correct database connection information and/or documents directory.

11. Start DocuShare 7 on your new server and verify that the site comes up ok.

12. Restore the DocuShare 7 IDOL indices or if IDOL indices are not restored you will be required to run a dsindex index_all on your DocuShare server.

To Restore the IDOL Content Index Data from Backup

1. Stop DocuShare.
2. Open a Command Prompt Window or Terminal Window.
3. Change into the <dshome>\bin directory.
4. Run idoltool –s resetserver all y and press Enter.
5. Start DocuShare.
6. Run the one of the following commands depending on your environment.

• idoltool.bat –s restore <path to backup directory> (Windows)
• idoltool.sh –s restore <path to backup directory> (Linux / Solaris).

Where <path to backup directory> is replaced with the path to the backup folder. For example, D:\content_backup.

Note: If you are running multiple content engines, the restore command will need to be modified and run on each content.

Example:

For content0: idoltool.sh -s restore /content0_backup0 content0

For content1: idoltool.sh -s restore /content1_backup0 content1

Below are examples of the information that will be displayed in the log files after performing the command line restore in step 6 above.

Example of the< dshome>/logs/idoltool.log:

20131021 15:40:22 -     Submitted DREINITIAL, jobid = 1

20131021 15:40:24 -     waitForJobCompletion: id = 1: Finished; documents processed: 0...

20131021 15:40:24 -   restore: Done.

Note: If you are running multiple content engines the logs displayed in examples below will be named slightly different and will be found in the following locations.

For Content0: <dshome>\IDOLServer\content0

• application.log

• index.log

For Content1: <dshome>\IDOLServer\content1

• application.log

• index.log

Example of the <dshome>/IDOLServer/IDOL/logs/content_index.log:

20131021 15:40:22 -     Submitted DREINITIAL, jobid = 1

20131021 15:40:24 -     waitForJobCompletion: id = 1: Finished; documents processed: 0...

20131021 15:40:24 -   restore: Done.

7. Once the restore has completed, run one of the following commands from the <dshome>\bin directory.

• Dsindex.bat -reindexSince MM/dd/yyyy-MM/dd/yyy index_all (Windows)

• Dsindex.sh -reindexSince MM/dd/yyyy-MM/dd/yyy index_all (Solaris)

Notee: The MM/dd/yyyy should be set to a date shortly before the backup was created.

Example: dsindex -reindexSince 05/01/2019-05/30/2019 index_all

This command re-indexes all objects with modified/create date at or after 05/01/2019 (inclusive) and before 05/30/2019 (exclusive).

13. Restore LDAP Configuration (if applicable)

1. Use your standard restore procedure to restore the DirectoryConfigLDAP.xml and the DirectoryConfigCommon.xml files to the <dshome>\config directory to the new DocuShare server.
2. Log into DocuShare as admin from the web UI
3. Click Admin Home | Account Management | Providers |Security Services.
4. Place a check mark in the checkbox to enable LDAP.
5. Click Directory Services under Account Management, on the pane on the left hand side of your web browser.
6. Place a check mark in the checkbox to enable LDAP.
7. Log out of DocuShare.

14. Restore Subscription Setup (if applicable)

1. Stop DocuShare
2. Open a Command Prompt window.
3. Change into the <dshome>\bin directory.
4. From the bin directory type dssetup and press Enter.
5. Confirm or change the DocuShare SMTP Server and the admin email address info when prompted if necessary.
6. When the settings changes have been completed, close the command prompt window.
7. Start DocuShare.

15. Custom Configuration Files (if applicable)

If the old Docushare server had any custom configurations such as Monitor.xml, SearchServer.xml, etc. Then these custom configuration files will have to be manually changed again or restored on your new server.

Note: If you are restoring the old Monitor.xml, SearchServer.xml etc. Then you will need to stop DocuShare before restoring. It is also recommended that you backup the fresh install Monitor.xml, SearchServer.xml, etc. files if you are restoring the backed up ones from the previous server so that you can revert back to the fresh install ones if you have a problem restoring them.

16. Restore Customized VDF files (if applicable)

To restore the customized VDF files.  Create a directory called local in the Xerox\DocuShare\amber\templates\<language> directory and restore the vdf files from the backup that were in the local directory to the new local directory.

17. If the old server is using SSL Certificates, then follow the procedure below to restore them on the new server. (if applicable)

1. On the old server browse to <dshome>\jdk\jre\lib\security and copy cacerts and dstruststore.

2. Restore to the new server’s <dshome>\jdk\jre\lib\security directory.

3. Once you have finished restoring, reboot your DocuShare server.

4. Start DocuShare.

5. Verify that the certificate is restored by doing the following:

   1. Open a Command Prompt window and change into the <dshome>\jdk\jre\lib\security directory.

   2. Type ..\..\bin\keytool -list -v -keystore <dshome>\jdk\jre\lib\security dstruststore

       

      Where <dshome> is replaced with the installation directory for DocuShare.

Note: When prompted for a password, just press enter. The DocuShare dstruststore does not have a password.

1. Examine the output to verify your certificate is listed.

Note: (Important for future maintenance) The security certificate has expiration date. This in-house certified Security certificate must be updated before it expires.  DocuShare does not have automated maintenance process to update the security certificate, so this must be done manually.

Solution Published: April 6, 2020

Solution ID: 2027