| Summary: On DocuShare 7.x, dsUpdate may fail when it is used to install patch JAR files from a different release or patch package. Use the newest dsUpdate supplied with the applicable DocuShare release package, and apply only patch JAR files that are documented as compatible with the installed release and patch sequence. |
Issue
The dsUpdate patch engine may report a failure when one or more patch JAR files are selected from another DocuShare release or from a different patch package. The main installation may appear to complete while one or more selected patches are not applied.
This article applies to DocuShare 7.x installations. On Linux, the patch engine is named dsUpdate without the .exe extension. On Windows, it is named dsUpdate.exe.
Why This Can Occur
DocuShare patch JAR files contain release-specific compatibility information. A patch can declare the DocuShare version it supports, and individual patch actions can be restricted to a specific DocuShare version. A patch from another release line may therefore be rejected or may skip its commands when it is run against the installed version.
The dsUpdate executable included with a release package is the version tested with that package. Using an older patch engine with a newer patch JAR can produce an installation failure or an incomplete result, even when the JAR is selectable in the installation wizard.
Before You Begin
| Backup required: Before installing any patch, create and verify a current backup. Do not begin the patch installation until the backup is complete and accessible for recovery. |
- Back up the DocuShare database.
- Back up the DocuShare content store and document data.
- Back up DocuShare configuration files, customizations, integrations, and add-ons.
- Back up license information and record the current DocuShare release and patch level.
- Verify that the backup completed successfully and retain it until the patch has been validated.
Follow the backup and recovery procedure appropriate for your DocuShare release and environment. If you cannot confirm that a usable backup is available, contact Xerox DocuShare Support before proceeding.
Recommended Resolution
- Confirm the installed DocuShare release and patch level from the DocuShare administration interface or product information page.
- Download the latest available DocuShare update, patch, or security release that applies to your release line.
- Extract the complete package and use the dsUpdate executable supplied with that package. Use dsUpdate.exe on Windows or dsUpdate on Linux.
- Select only patch JAR files documented as compatible with the installed DocuShare release and the required installation order.
- Run the installation during an approved maintenance window and follow the package documentation for stopping and restarting DocuShare.
- After the installation, confirm the expected patch level in DocuShare and test administrator login, document access, document download, and search.
| Important: Do not assume that a patch JAR from another DocuShare release can be installed simply because dsUpdate allows you to browse to and select the file. Do not combine patch JARs from different release lines unless the supplied documentation explicitly supports that sequence. |
Workaround
If installing several patch JAR files in one execution fails, run dsUpdate again and install only the patch JAR included with the same release package as the dsUpdate executable. Repeat the process using the documented patch order for your installed release.
- Use a complete patch archive, including its bundled dsUpdate executable and documentation.
- Do not replace the bundled dsUpdate with an older copy from another installation or patch archive.
- Do not retry a failed installation repeatedly without first recording the error and preserving the installation logs.
Collect Logs Before Retrying
Before closing the installer or retrying the operation, collect the dsUpdate log and any per-patch log files produced by the installation. Depending on the release and operating system, these may include dsupdate.log and temporary dsupd_*.log files.
- Record the installed DocuShare release and patch level.
- Record the name of every patch JAR selected and the package from which it was obtained.
- Record the dsUpdate executable used, including its file name, file version, and package source when available.
- Preserve the installation log, error message, screenshot, and the time of the failed attempt.
If the Problem Continues
Contact Xerox DocuShare Support if the patch still fails when you use the newest dsUpdate supplied with the applicable package and a documented patch sequence.
Provide the following information with the support request:
- DocuShare version, patch level, and operating system.
- Patch JAR names and download or package source.
- dsUpdate version or file properties, if available.
- Complete dsUpdate logs and any per-patch dsupd_*.log files.
- The exact error message and the step at which the installation failed.
- Whether the same-release patch JAR installs successfully by itself.
Related Guidance
- Always review the documentation supplied with the current DocuShare update before installing patches.
- Keep the verified backup until the patch installation and post-installation validation are complete.
- Customers with a valid support agreement should plan an upgrade to the latest supported DocuShare release and apply the latest available patches and security updates for that release.