Upgrading to new versions of the Muhimbi PDF Converter has always been relatively straight-forward. It is a matter of uninstalling the old version and installing the latest download. However, there are some points to take into account 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 (e.g. 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.
Please read all instructions below. 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, please consult this Knowledge Base article.
When upgrading the Muhimbi PDF Converter Services (not the Muhimbi PDF Converter for SharePoint), please 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:
- Please make sure you have a copy of the latest license key.
- Download the latest version of the PDF Converter.
- Follow section 2.8 Upgrading from a previous version, in the included Administration Guide.
Make sure to read the version specific notes below.
##Upgrading to 8.4 (Minimal .net 4.0 & 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. Please make sure that the server running the Muhimbi 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 Muhimbi's WSDL.
##Upgrading to 8.3 (Overhauled HTML Converter)**
The main change in the 8.3 release is a completely overhauled HTML converter (See this post for details). 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.
Please keep the following in mind:
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.
The Table of Content facility uses the HTML Converter in the background as well. If you are using this facility then please keep in mind 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.
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, if it is important that the HTML is converted to PDF EXACTLY like it looks on screen, then 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, follow guidance in the following Knowledge Base articles to troubleshoot conversions.
- Converting HTML - Empty page / Authentication problems.
- Solving formatting issues when converting HTML to PDF.
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 they 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:
Completely overhauled InfoPath converter (See this post for details). The main points to take into account are:
- 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 OS in combination with the new InfoPath converter, then 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 then please follow the manual installation steps for Ghostscript in our Admin Guide.
- The InfoPath converter can be switched post installation, in the Conversion Service's config file, using the UseNativePrintEngine setting.
Completely overhauled Setup experience (See this post for details). The main points to take into account are:
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 Muhimbi 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 paying close attention to chapter 2 of the latest Administration Guide.
Continue to follow the generic upgrading instruction at the top of this article.
As always, if you have any questions - or require assistance - then please contact our friendly support desk, we are here to help.