Upgrading Nutrient Document Converter

Upgrading to new versions of Nutrient Document Converter has always been relatively straight-forward. It is a matter of uninstalling the old version and installing the latest download. However, there are a few points to consider when upgrading between specific versions, especially when upgrading production servers.

We rarely (knowingly) break existing features, but from time to time we completely revamp part of the software (for example, the brand-new InfoPath converter in 8.0 and the new HTML converter in 8.3). We test our software very well, but we cannot test customer specific edge cases.

Information

- Read all instructions below carefully. If you are - for example - upgrading from 7.2 to 8.3 then the upgrading instructions for those versions, and all versions in between, need to be taken into account.
- Always follow best practices by upgrading a development or test server before upgrading your production server. Avoid deploying to production servers during office hours, if SharePoint behaves unexpectedly during or after the upgrade, contact us and we'll be happy to help.
- When upgrading Nutrient Document Converter Services (not Nutrient Document Converter for SharePoint), ignore all references to 'SharePoint'.

Generic upgrading instructions

Regardless of which version you are upgrading from, and which version you are upgrading to, the following steps are always the same:

  1. Make sure you have a copy of the latest license key.

  2. Download the latest version of the Document Converter.

  3. Follow the section Upgrading from a previous version.

Make sure to read the version specific notes below:

Upgrading to 8.4 (Minimal .NET 4.0 and Java Axis2 proxy classes)

One of the key changes in the 8.4 release is a move from .NET 3.5 to .NET 4.0. Make sure that the server running the Nutrient Conversion Service runs a version of .NET 4 (4.0 - 4.7.2 at the time of writing). As .NET 4.0 was released in 2010, most machines will already have a 4.x version installed.

Any custom developed Java applications based on the Axis2 web services framework will need to refresh the proxy classes. No code changes are required, but due to the way Axis2 works internally it will complain about some of the newer additions in Nutrient’s Web Services Description Language (WSDL).

Upgrading to 8.3 (Overhauled HTML Converter)

The main change in the 8.3 release is a completely overhauled HTML converter. For more information, see Converting HTML web content to PDF using SharePoint, C#, Java, and PHP. Although the old Internet Explorer based converter is still included, and can be switched to using the Conversion Service’s config file, it is generally recommended to use the new HTML Converter, which is enabled by default.

Note:

  1. The email converter (MSG, EML) uses the HTML Converter in the background depending on the content type of the email. This may lead to slightly different, and on average better, conversion results than in previous releases. Although there should be no need, if you have a reason to do so, you can switch the email converter back to the old HTML Converter using the MSGConverterFullFidelity.HtmlRendering_ _Engine config value.

  2. The Table of Content facility uses the HTML Converter in the background as well. If you are using this facility, remember that the sample XSLT shipped with previous versions has some unexpected side effects with the new HTML converter, which is enabled by default. To resolve this, either download the updated XSLT or switch back to the legacy HTML converter in the config file using the TableOfContent.HtmlRenderingEngine setting.

  3. The new HTML Converter is configured to use the Print_ CSS media type by default. This typically generates content that is much more suited to Print PDF output. However, you need to convert HTML to PDF exactly like it looks on screen, and switch the CSS Media Type from Print_ to _Screen using either the facility that you are using to carry out the conversion (Workflow Actions, API etc) or switch the setting globally in the config file using the HTMLConverterFullFidelity.MediaType setting.

This new HTML Converter is much improved and generally generates much better output when it comes to conversion of SharePoint pages. However, as HTML is not the best language for generating PDF and Print output, following articles can help you troubleshoot conversions:

Another key change in the 8.3 release is related to how image-based files (excluding TIFFs) are now handled by the new Image converter. Previously image-based files were handled by the HTML converter. Other than increased performance, there should be no noticeable impact unless you manually modify the list of converters in the service’s config file, or use the web service interface to query the list of available converters.

Upgrading from a pre-8.0 release (Overhauled InfoPath Converter and Installer)

The key changes in the 8.0 release are as follows:

  1. Completely overhauled InfoPath converter. For more information, see Introducing the new high fidelity InfoPath converter. Following are the important points to consider:

    • Use the installer to control which InfoPath converter to use. Although discouraged, you have the option to use the old legacy InfoPath converter.

    • The new InfoPath Converter can only be used on Windows Server 2008 or newer.

    • When using a 64-bit operating system in combination with the new InfoPath converter, the 64-bit version of InfoPath must be installed alongside the converter. The 32-bit version of InfoPath is not supported on 64-bit systems.

    • The new InfoPath converter uses Ghostscript in the background. The installer makes it possible to automatically download and install this dependency. If your system cannot connect to the internet, contact us and we’ll be happy to help.

    • The InfoPath converter can be switched post installation, in the Conversion Service’s config file, using the UseNativePrintEngine setting.

  2. Completely overhauled Setup experience. For more information, see PDF converter new setup experience. Following are the important points to consider:

    • Follow the generic upgrading instructions at the top of this article.

    • Use the following steps to uninstall the old (pre-8.0) version:

      • Conversion Service: Use ‘Add/Remove programs’ to uninstall the Nutrient Conversion Service.

      • SharePoint front end: Run uninstall.cmd, which comes with the install set of the old installer. If the install set is no longer available, retract and delete all Muhimbi.pdfconverter.\*.wsp files from the Central Administration Solution Management screen.

      • License Manager: Repeat the same step for muhimbi.licensing.\*.wsp.

    • Deploy the latest (8.0 or later) release. For more information, see Document Converter guides.

    • Continue to follow the generic upgrading instruction at the top of this article.

As always, if you have any questions or require assistance, contact us and we’ll be happy to help.