Skip to main content

How to Migrate DocuShare 7.0 to a New DocuShare 8.0 Server (Retaining IDOL Search)

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

 

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

 

Search engine:  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

  • The 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, back up all your customizations, then apply the customizations to the new DocuShare 8.0 site once migrated. 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, notify DocuShare 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 suitable for your environment.
  • If you use the Scan Cover Sheet functions of DocuShare (Glyphscan) and you change the DocuShare server's IP address or hostname, HTTP protocol, HTTP port, or DocuShare root, you may need to delete and re-create all scan cover pages. The dataglyph on the bottom of a scan cover sheet encodes your server's URL.

Part 1 of 2: Install DocuShare 7.0 Fresh on the New Server and Restore Backup From the Old 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 that information will be overwritten.

 

  1. Upgrade to DS 7.0 Update 1 Patch 3.
  2. Verify the bucket structures of the old server and the new server match.
Warning:  This step is very important. 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 the installation directory for DocuShare. The default installation directory is C:\Xerox\Docushare; the path may vary in your environment.
  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 the next step. 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.
  4. On the newly installed DocuShare 7.0 server, open <dshome>\config\ContentStore.properties in a text editor. Look for an entry called NumberOfDirectories= and edit this value to match the value found on the old server, then save the changes.
  5. On the newly installed DocuShare 7.0 server, open <dshome>\config\ContentStore.xml 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 that the data retention value matches the old server. If the value was changed from the default of 365 days to a higher number of days or infinite on the old server, and the new server does not match, DocuShare will purge access data older than 365 days when it first starts on the new server after the restore. This can also cause the database transaction log to fill up and slow DocuShare down.

 

  1. On the old server, log into DocuShare as admin, open Windows Explorer, and navigate to <dshome>\config.
  2. Open DSServer.properties and search for the numberOfAccessDaysToKeep= value.
  3. If the value is anything other than 365, start DocuShare on the newly installed server and change the value to match the old server.
  4. Put the old site in Read Only mode or stop DocuShare. This prevents 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.
  5. Backup the old DocuShare site. Use your standard backup procedure to back up DocuShare. See the minimum requirements and recommendations below.

Minimum Backup Requirements

To keep database information and site information in sync, 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 are 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 | 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, back up 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, back up the entire Xerox\Docushare install directory. This backs up all site content located under the Xerox\Docushare directory, including configuration files and site customization files.

  1. Back up the IDOL index on the old server (optional).
Note:  If you choose not to back up IDOL, you will need to run dsindex index_all on the new server for search capabilities. Depending on the size of your site, 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.
idoltool.bat -s backup D:\content_backup

 

Note:  The backup will need to be run on each content engine if you are running more than one. The command line statement will need to be modified for each content engine, and the server argument is required. Omitting it when more than one content engine is configured fails immediately with: Error: No server parameter specified.

 

idoltool.bat -s backup c:\idolbackup content0
idoltool.bat -s backup c:\idolbackup content1
idoltool.bat -s backup c:\idolbackup content2

 

  1. After performing a backup, review the log files to confirm completion.

If you are running one content engine, <dshome>/logs/idoltool.log will display:

Submitted DREBACKUP, jobid = 19
IdolAdmin.waitForJobCompletion: id = 19: Finished; documents processed: 0...
backup: Done.

 

If you are running multiple content engines, the logs will be named application.log and index.log and found under <dshome>\IDOLServer\content0, <dshome>\IDOLServer\content1, and so on. The <dshome>\IDOLServer\IDOL\logs\content_application.log will show an entry such as Backup Complete. when finished, and content_index.log will show an entry such as Index command finished.

  1. On the new DocuShare server, use your standard restore procedure to restore the backed up DocuShare database.
  2. Use your standard restore procedure to restore the content store repository.
Restore location:  Restore the content store repository to the document repository location configured for the new server. This is normally <dshome>\IDOLServer\documents, but the actual location can vary by installation. Confirm the exact path from the Document Repository field on the Site Management | Directory Paths Admin UI page on the new server before restoring.

 

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 is different from what the initial installation points to, run dssetup from the Command Prompt in the <dshome>\bin directory and point to the correct database connection information and/or documents directory.

 

  1. Restore LDAP configuration (if applicable). Use your standard restore procedure to restore the DirectoryConfigLDAP.xml, AuthConfigCommon.xml, and DirectoryConfigCommon.xml files to the <dshome>\config directory on the new DocuShare server.
  2. Restore Subscription setup (if applicable).
  3. Open a Command Prompt window and 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 when prompted, if necessary.
  6. When the settings changes are complete, close the command prompt window.
  7. 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 and matching the old server's values.

 

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

  1. Custom configuration files (if applicable). If the old DocuShare server had custom configurations such as Monitor.xml or SearchServer.xml, these files will need to be manually reconfigured or restored on your new server.
Note:  If you are restoring the old Monitor.xml, SearchServer.xml, or similar files, stop DocuShare before restoring. It is also recommended that you back up the fresh install versions of these files first, so that you can revert if you have a problem restoring the backed-up ones.

 

  1. 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.
  2. If the old server uses SSL certificates, follow the procedure below to restore them on the new server (if applicable).
  3. On the old server, browse to <dshome>\jdk\jre\lib\security and copy dstruststore.
  4. Restore it to the new server's <dshome>\jdk\jre\lib\security directory.
  5. Once restoring is finished, reboot your DocuShare server.
  6. Start DocuShare.
  7. Verify the certificate is restored: open a Command Prompt window, change into the <dshome>\jdk\jre\lib\security directory, and type ..\..\bin\keytool -list -v -keystore dstruststore.
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.
Important for future maintenance:  The security certificate has an expiration date. This in-house certified security certificate must be updated before it expires. DocuShare does not have an automated process to update the security certificate, so this must be done manually.

 

  1. Start DocuShare 7.0 on your new server and verify that the site comes up correctly and the content is restored correctly.
  2. 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.

 

Note:  Log into the Server Operating System as a local Administrator to ensure 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.
  3. Start the upgrade by right-clicking docushare.exe and selecting Run as Administrator. Be patient; it takes several minutes before the first install wizard screen appears.
  4. When the Upgrade Option window appears, select the appropriate upgrade. Be patient; it takes several minutes for the installer to load and start.
  5. Follow the onscreen instructions; accept the defaults or enter your own configuration information.
  6. Finish the upgrade. When it completes successfully, 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, open the Administrative Tools Services application 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 old server's Host ID, the new server's Host ID, and the version of DocuShare being installed. The new license key must cover at least the same number of users as the previous license.

 

  1. If the DocuShare site uses LDAP over a secure SSL channel, import the SSL certificate into <dshome>\jdk\lib\security\cacerts, for example if you use your own self-signed certificate.
  2. 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.
  3. 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.
Why this step is used here:  This is a new-server migration, not a routine restore onto an already-populated site. resetserver initializes the freshly installed IDOL server on the new machine before the index is restored. It is not a step you need to repeat for a normal, day-to-day IDOL restore on an existing, already-configured server; see the separate IDOL backup and restore articles for that scenario. This command is destructive and requires DocuShare and IDOL to be fully stopped; it aborts if the target server is still running.

 

  1. Start DocuShare.
  2. From the <dshome>\bin directory, type idoltool.bat -s restore <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.
Note:  If you are running multiple content engines, the restore command needs to be modified and run on each content engine. Omitting the server argument when more than one content engine is configured fails immediately with: Error: No server parameter specified.

 

idoltool.sh -s restore /content0_backup0 content0
idoltool.sh -s restore /content1_backup0 content1

 

The log files will show information after performing the command line restore. Example of <dshome>/logs/idoltool.log:

Submitted DREINITIAL, jobid = 1
waitForJobCompletion: id = 1: Finished; documents processed: 0...
restore: Done.

 

Note:  If you are running multiple content engines, the logs will be named application.log and index.log and found under <dshome>\IDOLServer\content0 and <dshome>\IDOLServer\content1. Confirm restore: Done. for every content engine before continuing.

 

  1. Once the restore has completed, run the reindex command from the <dshome>\bin directory.
dsindex.bat -reindexSince MM/dd/yyyy-MM/dd/yyyy index_all

 

Date range is half-open:  The start date is inclusive and the end date is exclusive. Set the first date shortly before the backup was created, and set the end date to one day past the last day you need covered, or that day's changes will not be reindexed. Example: dsindex -reindexSince 05/01/2019-05/30/2019 index_all re-indexes all objects with a modified or create date at or after 05/01/2019 (inclusive) and before 05/30/2019 (exclusive).

 

Option 2: Do a Full Reindex of the Site

Warning:  Depending on the size of your site and the content, a full reindex 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.
  3. Post-upgrade tasks.
  4. Run database optimization as defined in the DocuShare Administrator Guide database optimization procedures. Detailed information on maintaining and optimizing the database is also available in our Knowledge Base; search for the keyword optimize.
  5. 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 restored earlier in this procedure will continue to serve search queries without modification. If you restored from backup (Option 1) or performed a full reindex (Option 2) above, your search functionality is now restored.
  • Solr, an 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:

  • Migrating from IDOL to Solr requires a full reindex of all DocuShare content, which may take significant time on large sites.
  • There are differences between IDOL and Solr that 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, or contact DocuShare Support by emailing docushare.support@xerox.com.

Related Resources

  • How to migrate DocuShare 7 to a new DocuShare 8.0 Server on Windows
  • DocuShare 8.0 System Requirements
  • DocuShare 8.0 Upgrade Paths
  • How to upgrade to DocuShare 8.0 (In-place upgrade)

Related articles