Skip to main content

Upgrade path to DocuShare 8.0 when migrating to a new server

Updated

Note: This article is applicable to DocuShare 7.0 needing to be upgraded to 8.0 on a new server.

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

Note: This procedure retains the IDOL Search Engine as the active search engine on the upgraded DocuShare 8.0 site. Customers running DocuShare 7.0 with IDOL are not required to migrate to Solr as part of this upgrade. IDOL is fully supported in DocuShare 8.0. If you would like to review the differences between IDOL and Solr, or explore migrating to Solr in the future, refer to the 'Search Engine Options' section at the end of this article.

Prerequisites:

  • Existing server must already be a DocuShare 7.0 Server. If the existing server is running an older version of DocuShare, contact DocuShare Support to discuss an upgrade path suitable to your environment.
  • DocuShare must be at DocuShare 7.0 Update 1 Patch 3 before upgrade.

Before you start

Review the System Requirements for DocuShare 8.0 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 8.0 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 Sales 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 of 2: Install DocuShare 7.0 Fresh on the new Server and restore backup from old DocuShare 7.0 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 with Update 1 on the new server

    Note: For the purposes of this migration, temporarily installing DocuShare 7.0 on Windows Server 2019, 2022, or 2025 is supported. 

    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.

     

  2. Upgrade to DS 7.0 Update 1 Patch 3.

  3. 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. 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.
    2. Open the ContentStore.xml file in a text editor and look for an entry called <NumberOfBuckets>512</NumberOfBuckets>.
    3. If the value is 512 you can skip to step 4.
    4. 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.
    5. 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.
    6. Look for an entry called NumberOfDirectories= edit this value to match the value found in step 3.2 on the old server. Then save the changes.
  • On the newly installed DocuShare 7.0 Server, Open the <dshome>\config\ContentStore.xml file in a text editor.

  • Look for the entry <NumberOfBuckets>512</NumberOfBuckets> and 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 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.

     

    1. On the old server, log into DocuShare as admin.
    2. On the old server, open Windows Explorer and navigate to <dshome>\config directory.
    3. Open the DSServer.properties file and search for the numberOfAccessDaysToKeep= value.

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

       

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

    Log into DocuShare as admin, click Admin Home | Site Management | Site Operations. In the System Mode field, select Read Only and click the Apply button.

     

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

     

  4. 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 of your site, a dsindex index_all can take a long time to complete. If you plan to explore migrating to the Solr search engine after the upgrade, you do not need to restore the IDOL index - a full Solr index will be built separately as part of that process. See the 'Search Engine Options' section at the end of this article for more information.

    To perform a manual backup of IDOL Index data

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

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

       

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

       

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

  6. Use your standard restore procedure to restore the content store repository (<dshome>\IDOLServerdocuments 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 to run dssetup from the Command Prompt in the <dshome>\bin directory and point to the correct database connection information and/or documents directory.

     

  7. Restore LDAP Configuration (if applicable)

    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.

  8. Restore Subscription Setup (if applicable)
    1. Open a Command Prompt window and change into the <dshome>\bin directory.
    2. From the bin directory type dssetup and press Enter.
    3. Confirm or change the DocuShare SMTP Server and the admin email address info when prompted if necessary.
    4. When the settings changes have been completed, close the command prompt window.

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

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

     

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

     

  11. Restore Customized VDF files (if applicable)

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

     

  12. 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 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:
    6. Open a Command Prompt window and change into the <dshome>\jdk\jre\lib\security directory.

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

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

  13. Start DocuShare 7.0 on your new server and verify that the site comes up ok and the content is restored correctly.
  14. Stop DocuShare.

Part 2 of 2: Upgrade the new DocuShare 7.0 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. Verify that your New DocuShare 7.0 Server has Update 1 Patch 3 installed. This is a prerequisite to upgrade.
  2. Download the required DocuShare 7.7 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. Repeat steps 2 through 6 with DocuShare 7.7 Patch 1, then repeat steps 2 through 6 again with DocuShare 8.0 and any applicable patches or hot fixes, installing each in sequence.
  8. Reboot the server.
  9. 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.

  10. License the new DocuShare 8.0 site.

    Note: DocuShare Licensing can be reached by emailing docushare.licenses@xerox.com. The licensing department will require the servers old Host ID, the new Host ID, and version of DocuShare. The new key you are applying needs to have the same number of users.

     

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

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

     

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

      1. Stop DocuShare.
      2. Open a Command Prompt Window and change into the <dshome>\bin directory.
      3. Run idoltool -s resetserver all y and press Enter.
      4. Start DocuShare.

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

         

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

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

      2. Type dsindex index_all and press Enter.

         

  14. Post upgrade tasks

    1. 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 Knowledge Base, search for the keyword optimize.

       

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

 

Search Engine Options in DocuShare 8.0

DocuShare 8.0 supports two search engines: IDOL and Solr. This upgrade procedure retains IDOL as your search engine. No further search configuration is required to complete this upgrade.

  • IDOL in DocuShare 8.0: Your existing IDOL Search Engine configuration is fully supported in DocuShare 8.0. The IDOL index that was restored earlier in this procedure will continue to serve search queries without modification. If you restored from backup (Option 1) or performed a full re-index (Option 2) in Step 13 above, your search functionality is now restored.

     

  • Solr - Optional Future Path: If you would like to explore migrating from IDOL to Solr in the future, DocuShare 8.0 includes full documentation for this migration path. Migrating to Solr is optional and independent of this server migration.

    Key considerations when comparing IDOL and Solr include the following:

    • Migrating from IDOL to Solr requires a full re-index of all DocuShare content, which may take significant time on large sites.
    • There are differences between IDOL and Solr which could affect user experience. Search results, for example, could differ between search engines.
    • Solr is the strategic search engine for new DocuShare 8.0 installations and future development.
    • IDOL continues to be supported in DocuShare 8.0 for customers who choose to retain it.
    • For full documentation on migrating from IDOL to Solr, refer to the DocuShare 8.0 documentation library located here:  https://docushare.xerox.com/doug/dsweb/View/Collection-19800 or contact DocuShare Support by emailing docushare.support@xerox.com.

Related articles