Upgrade path to DocuShare 7.5 when migrating to a new server

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

Note: When a site is upgraded to DocuShare 7.5 it will continue to use the IDOL Search Engine. There is currently no upgrade path to move to Solr search engine.

Prerequisites:

·         Existing server must already be a DocuShare 7.0 Server. If the existing server is running an older version of DocuShare, discuss an upgrade path suitable to your environment.

·         DocuShare must be at DocuShare 7.0 Update 1 Patch 3 to upgrade to 7.5.

Before you start

·         Review the System Requirements for DocuShare 7.5 and verify that your new server meets all the 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.

Part 1: Install DocuShare 7 Fresh on the new Server and restore backup from old DocuShare 7 Server.

Note: It is recommended that you temporarily disable your antivirus during the installation. The software may cause issues based on the antivirus used and the settings deployed.

Note: Log into the Server Operating System as a local Administrator. This will ensure that the account has enough privileges to install DocuShare.

1.     Install DocuShare 7.0 on the new server.

Note: For the purpose of doing an in-place upgrade to DocuShare 7.5, installing DocuShare 7.0 on a Windows 2019 Server temporarily will work.

2.     Install to the same path as the old server. (For example: C:\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.

3.     Start and license the new DocuShare 7.0 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.

4.     Once the new DocuShare 7.0 site is licensed, stop the new DocuShare 7.0 site.

5.     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.

a.     On the old server, open Windows Explorer and navigate to <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.

b.     Open the ContentStore.xml file in a text editor and look for an entry called <NumberOfBuckets>512</NumberOfBuckets>.

a.     If the value is 512 you can skip to step 6.

b.     If the value is 64 make a note of this value. The newly installed DocuShare 7.0 Server must be edited to match the old server’s values.

                                          i.    On the newly installed DocuShare 7.0 Server, open Windows Explorer and navigate to <dshome>\config\ContentStore.properties file and open in a text editor.

                                         ii.    Look for an entry called NumberOfDirectories= edit this value to match the value found in step b on the old server. Then save the changes.

                                        iii.    On the newly installed DocuShare 7.0 Server, Open the <dshome>\config\ContentStore.xml file in a text editor.

                                        iv.    Look for the entry <NumberOfBuckets>512</NumberOfBuckets> edit his 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.

6.     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 value was changed from the default value of 365 days to a higher number of days or infinite days on the old server and the new server does not match that same value then DocuShare will start purging the access data that is older than 365 days when DocuShare is first starting up on the new server after the restore. Also, in addition to deleting access tracking data (which may be critical for some businesses), it may result in database transaction log to get full and bog down DocuShare.

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

b.     On the old server, open Windows Explorer and navigate to <dshome>\config directory.

c.     Open the DSServer.properties file and search for the numberOfAccessDaysToKeep= value.

d.     If the value is anything other than 365, you need to start DocuShare on the newly installed server and change the value to match the old server.

7.     Put the old site in READ ONLY mode or Stop DocuShare. This will prevent any new content from being added after the backup is taken.

a.     Log into DocuShare as admin, click Admin Home | Site Management | Site Operations.

b.     In the System Mode field select Read Only and click Apply button.

8.     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 backup 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.

9.     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

a.     Open a command prompt window and change into the <dshome>\ bin directory.

b.     Type idoltool.bat –s backup <path_to_backup_directory> and press Enter.

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

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 (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

c.     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 multipleContent engines, the logs will be named slightly different (application.log and index.log) and will be found in the following locations.

For Content0: <dshome>\IDOLServer\content0

For Content1: <dshome>\IDOLServer\content1

The <dshome>\IDOLServer\IDOL\logs\content_application.log will have an entry like this when its complete: 21/10/2013 13:36:44 [1] Backup Complete.

The <dshome>\IDOLServer\IDOL\logs\content_index.log will have an entry like this when its complete: 27/09/2011 13:16:42 [1] Index command finished. Took 2.88 s

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

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

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

Note: 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.

12.  Restore LDAP Configuration (if applicable)

a.     Use your standard restore procedure to restore the DirectoryConfigLDAP.xml, AuthConfigCommon.xml and the DirectoryConfigCommon.xml files to the <dshome>\config directory to the new DocuShare server.

13.  Restore Subscription Setup (if applicable)

a.     Open a Command Prompt window and change into the <dshome>\bin directory.

b.     From the bin directory type dssetup and press Enter.

c.     Confirm or change the DocuShare SMTP Server and the admin email address info when prompted if necessary.

d.     When the settings changes have been completed, close the command prompt window.

14.  Restore Content Intake Sockets (CIM) (If applicable)

Warning: Before restoring CIM sockets, you must have the directory paths that the CIM sockets point to created to match the old server’s values.

a.     Use your standard restore procedure to restore the <dshome>\config\IngersterService.xml file directory to the new DocuShare server.

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)

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

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

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

d.    Start DocuShare.

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

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

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

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

                    iii.        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.

18.  Start DocuShare 7 on your new server and verify that the site comes up ok and the content is restored correctly.

Part 2: Upgrade the new DocuShare 7.0 Server to DocuShare 7.5

Note: It is recommended that you temporarily disable your antivirus during the installation. The software may cause issues based on the antivirus used and the settings deployed.

Note: Log into the Server Operating System as a local Administrator. This will ensure that the account has enough privileges to install DocuShare

1.     Verify that your New DocuShare 7.0 Server has Update 1 Patch 3 installed. This is a prerequisite to upgrade to DocuShare 7.5.

2.     Download the DocuShare 7.5 software to a temporary directory on your server. Unzip and extract the file locally to the system.

3.     Start the upgrade by right clicking the docushare.exe and selecting Run as Administrator. Be patient; it takes several minutes before the system displays the first install Wizard screen.

4.     When the Upgrade Option window appears, select the appropriate Upgrade. Be patient; it takes several minutes for the system to load and start the installer.

5.     Follow the onscreen instructions; accept the defaults or enter your own configuration information.

6.     Finish the upgrade. When the upgrade successfully completes, click Finish to close the installer.

7.     Reboot the server.

8.     After the server restarts, if you did not set DocuShare to run as an AutoStart service, do the following: In the Administrative Tool, in the Services application, select and start the DocuShare service.

9.     If the DocuShare site uses LDAP over a secure SSL channel, you need to import the SSL certificate into in <dshome>\jdk\lib\security\cacerts. For example, in the case you use your own self-signed certificate.

10.  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 the IIS console, and restart the service.

11.  Restore the DocuShare 7 IDOL indices using one of the following methods:

• Option 1: Restore the IDOL Content Index Data from Backup

a.     Stop DocuShare.

b.     Open a Command Prompt Window and change into the <dshome>\bin directory.

c.     Run idoltool –s resetserver all y and press Enter.

d.     Start DocuShare.

e.     From the <dshome>\bin directory type idoltool.bat –s restore <path to backup directory>

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 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. Example: For Content0: <dshome>\IDOLServer\content0 (application.log and index.log) for Content1: <dshome>\IDOLServer\content1 (application.log and 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.

f.      Once the restore has completed, type <dshome>\bin\Dsindex.bat -reindexSince MM/dd/yyyy-MM/dd/yyy index_all and press Enter.

Note: 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).

• Option 2: Do a full re-index of the site.

Warning: Depending on the size of your site and the content a full re-index can take hours or days to complete.

a.     Open a Command Prompt window and change into the <dshome>\bin directory.

b.     Type dsindex index_all and press Enter.

12.  Post upgrade tasks

a.     Run database optimization as defined in the DocuShare Administrator Guide database optimization procedures.

Note: Detailed information on how to maintain and optimize the database is also available in our customer KB available at http://customer.docushare.com/ search for the keyword optimize.

b.     Refer to the DocuShare VDF Reference Guide to migrate your custom VDFs to the current DocuShare release. (if applicable)

Solution Published: February 8, 2021

Solution ID: 2103