Skip to main content

How to migrate DocuShare 7 to a new DocuShare 8.0 Server on Windows

Updated

Use this procedure if you are migrating your DocuShare 7.0 site directly to DocuShare 8.0 on a new server AND you are ready to move to the Solr search engine. This procedure upgrades the database schema using the setupDB utility and performs a full Solr re-index. The previous IDOL search index is not carried forward. If you want to retain the IDOL search engine on DocuShare 8.0, refer instead to the article: 'Upgrade path to DocuShare 8.0 when migrating to a new server.'

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

Prerequisites: 

  • The original DocuShare site must be at version 7.0 Update 1 Patch 3 or higher.
  • You must have access to a backup of the DocuShare 7 database and documents directory.
  • You must have access to the SQL Server (or equivalent database server) to restore a copy of the database.
  • DocuShare must be installed and initially licensed on the new server before you restore data.

Warning: A full Solr re-index of the site is required as part of this migration. Depending on the size of your site, this may take several hours or days to complete.

Note: It is recommended that you temporarily disable your antivirus during the DocuShare installation. Some antivirus products may interfere with the installer depending on their configuration

To migrate DocuShare 7 to a new DocuShare 8.0 Server:

Note: Log into the Server Operating System as a local Administrator before installing. This ensures the installer has sufficient privileges

  1. Install DocuShare 8.0 on the new Windows server.
  2. Do not start the new DocuShare 8.0 server yet. Navigate to <dshome>\config and delete the file named nebula (the file has no extension). This file contains the server identity from the fresh installation and must be removed before restoring the old database so that DocuShare generates a fresh identity on first startup.

  3. Start and license the new DocuShare 8.0 site.

    Licensing note: 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.

     

  4. Once the new DocuShare 8.0 site is licensed, stop it.

  5. Verify the Bucket Structures of the backed-up server and the new server match (If applicable)

    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 DocuShare 7 server:
      1. Open Windows Explorer
      2. Navigate the folder structure into the <dshome>\config directory.
      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 newly installed DocuShare 8.0 server has the same bucket structure as the server that was backed up.
      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 5-1. 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.

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

    To verify the access tracking value on the old server:

    1. On the OLD DocuShare 7 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 installation 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.

       

    4. To verify the newly installed DocuShare 8.0 server has the same access tracking value as the old server:
      1. On the NEW DocuShare 8.0 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.

      4. Set the value to match the old server.

         

  7. Back up the old DocuShare 7 server before proceeding. At a minimum, back up.
    1. The DocuShare database - for SQL Server, this includes Docushare.mdf and Docushare_log.LDF.
    2. The documents (content store) directory - located at <dshome>\documents or the path shown in Admin Home | Site Management | Directory Paths.

    3. The <dshome>\config directory. Stop DocuShare or place it in Read Only mode before taking the backup to ensure database and file consistency. Refer to the DocuShare Administrator Guide for full backup procedures.

       

  8. Restore a COPY of the OLD DocuShare 7 database to the NEW DocuShare 8.0 Server. This is the Database you connect to in DocuShare. For example, SQL Server.

    Warning: Do not point your new server to the same database that your OLD DocuShare 7 Server is connected to. You should be pointing to a COPY of the database either on your existing Database Server or a New Database Server that is attached to a COPY of the old database.

    Note: To create a copy, use SQL Server Management Studio (or equivalent) to restore a backup of the DocuShare database under a new database name on the new or target SQL Server instance.

    Warning: Do not detach and reattach the original .mdf file while the old DocuShare 7 server is still active.

     

  9. From a Command Prompt (Run as Administrator), change into the <dshome>\bin directory, run dssetup. When prompted, update the database connection settings to point to the restored COPY of the DocuShare 7 database on the new server. Complete all other prompts and close dssetup when finished.
  10. Download and install setupDB 8.0 utility on the new DocuShare 8.0 Server. Download is available here https://docushare.xerox.com/doug/dsweb/View/Collection-19816. Note: a readme.txt with install instructions is included with utility.
  11. On the NEW DocuShare 8.0 Server, open a command prompt window (Run as Administrator).
  12. Change into the <dshome>\bin directory.
  13. Type setupDB -v 08.00.00 and press Enter. Wait for the command to complete before proceeding.

  14. Once the command completes, restore the content store repository (documents directory).

    Warning: When restoring the Content Store, do not overwrite or delete the guid.txt file.

     

  15. After restoring the content store, perform the following restorations as applicable to your environment before starting DocuShare:
    1. LDAP Configuration (if applicable):  Restore DirectoryConfigLDAP.xml, AuthConfigCommon.xml, and DirectoryConfigCommon.xml to the <dshome>\config directory on the new server.
    2. Subscription / SMTP Setup (if applicable):  From the <dshome>\bin directory, run dssetup and confirm or update the DocuShare SMTP Server and admin email address when prompted.
    3. Content Intake Sockets / CIM (if applicable):  Ensure all directory paths referenced by CIM sockets exist on the new server, then restore <dshome>\config\IngesterService.xml.
    4. Custom Configuration Files (if applicable): If the old server had custom Monitor.xml, SearchServer.xml, or similar files, stop DocuShare, back up the fresh install versions, then restore the old custom versions.
    5. SSL Certificates (if applicable):  Copy <dshome>\jdk\lib\security\cacerts or <dshome>\jdk\jre\lib\security\dstruststore on the old server to the same directory on the new server. Verify the certificate after restoring using keytool.
  16. Start DocuShare 8.0.

  17. Remove the old IDOL queue names not being used with Solr.

    With DocuShare running, open a Command Prompt (Run as Administrator) and change into the <dshome>\bin directory, then run the following commands:

    Note: DocuShare must be running when you execute diagevent. The tool connects to the live server over RMI to perform queue operations. If DocuShare is not running, diagevent will fail to start. If you need to remove queues without DocuShare running, use the SQL fallback shown below instead.

    diagevent remove indexingQ

    diagevent delete indexingQ

    diagevent remove indexingQ2

    diagevent delete indexingQ2

    Note: If your DocuShare site was already running Solr before this migration, the indexingQ and indexingQ2 queue entries may already be absent. If the diagevent commands return an error indicating a queue was not found, this is expected and no further action is required for that queue.

    Note: If the diagevent commands above return an error, you may use the SQL queries below as an alternative. Before running any direct database queries, it is recommended to contact DocuShare Support or take a backup of the database. These commands should only be run on the new database copy, never on the production database.

    1. Stop DocuShare.

    2. Run the SQL query in the database:

      DELETE FROM namedlisteners WHERE queuename='indexingQ' or queuename='indexingQ2';
      DELETE FROM indexRecovery;
      DELETE FROM eventTable;
      DELETE FROM eventObjectTable;

    3. Start DocuShare.
  18. Index your site using the following command.
    1. Open a Command Prompt window (Run as Administrator).

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

      Type dsindextool index_all and press Enter.

      Note: This process could take several hours or days depending on the size of your DocuShare site and its contents.

  19. After the index completes, perform the following post-upgrade tasks:
    1. Database Optimization - Run database optimization as described in the DocuShare Administrator Guide. Additional guidance is available in the Knowledge Base by searching the keyword 'optimize'.
    2. Custom VDFs (if applicable) - Refer to the DocuShare VDF Reference Guide to migrate any custom VDF files to the DocuShare 8.0 release.

 

Related articles