61
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 51 of 60
//wordLicence.SetLicense("Enter your license in here.");
Document asposeDocument = new Document(_sourceFile, null,
LoadFormat.Auto, _openOptions.Password);
// ** Do we need to refresh the fields etc?
if (_openOptions.RefreshContent == true)
asposeDocument.Range.UpdateFields();
// ** Convert the Document to PDF and save it as a memory stream.
if (_conversionSettings.Format == OutputFormat.PDF)
{
MemoryStream convertedStream = new MemoryStream();
PdfOptions options = new PdfOptions();
// ** Specify the PDF Profile
if (_conversionSettings.PDFProfile == PDFProfile.PDF_1_5)
options.Compliance = PdfCompliance.Pdf15;
else
options.Compliance = PdfCompliance.PdfA1b;
// ** How to deal with bookmarks
if (_conversionSettings.GenerateBookmarks ==
BookmarkGenerationOption.Automatic)
options.HeadingsOutlineLevels = 9;
else if (_conversionSettings.GenerateBookmarks ==
BookmarkGenerationOption.Custom)
options.BookmarksOutlineLevel = 9;
// ** Correct the start and end pages if needed
int startPage = _conversionSettings.StartPage != 0 ?
_conversionSettings.StartPage - 1 : 0;
int pageCount = asposeDocument.PageCount - startPage;
if (_conversionSettings.EndPage != 0)
pageCount = Math.Min(_conversionSettings.EndPage - startPage,
pageCount);
// ** Carry out the actual conversion
asposeDocument.SaveToPdf(startPage, pageCount, convertedStream,
options);
return convertedStream;
}
else
{
throw new NotSupportedException("Outputformat '" +
_conversionSettings.Format +
"' not supported by this Converter.");
}
}
catch (UnsupportedFileFormatException ex)
{
throw new WebServiceInternalException(
WebServiceExceptionType.FileFormatNotSupported, ex.Message);
}
catch (Exception ex)
{
string message = "An error occurred while converting a file";
if (_openOptions != null && _openOptions.OriginalFileName != null)
message += " - " + _openOptions.OriginalFileName;
Logger.Error(message, ex);
throw new WebServiceInternalException(
WebServiceExceptionType.InternalError, message);
}
}
47
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 52 of 60
10.
Compile the project and copy the output DLL as well as Aspose.Words.dll to the
directory that holds the Muhimbi Document Conversion Service.
11.
Edit the service's config file and make the following changes:
If the file extensions for the new converter are currently handled by a
different converter then remove these extensions from the existing
converter.
Add the definition for the new converter to the config file as per the
following example. For details see 2.6.6 Adding custom converters /
changing file extensions.
<add key="CustomWordConverter"
description="Custom MS-Word Converter"
fidelity="Full"
supportedExtensions="doc,docx"
type="Muhimbi.DocumentConverter.WebService.CustomConverters.WordConverter,
Muhimbi.DocumentConverter.WebService.CustomConverters,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
12.
Restart the service to activate the changes.
Net stop "Muhimbi Document Converter Service"
Net start "Muhimbi Document Converter Service"
13.
Finally test if everything is working correctly, either from:
SharePoint: Open Central Administration / Application Management /
Muhimbi Document Converter Settings (In SharePoint 2010/2013 this
screen is located in Central Admin / General Application Settings / Muhimbi
Document Converter Settings), verify that the new converter is added to the
list, check the tick box and click Validate Settings. If everything is working
correctly then don’t forget to save the changes using the
OK button.
Winforms Diagnostics Tool: Launch the Diagnostics Tool from the Windows
Start Menu, navigate to the WS Diagnose Tab and click the Request
Diagnostics button. Verify the new converter is listed and Valid = True.
Any errors are logged to the Windows Application Event Log.
Congratulations, you have created your first custom converter. Source code for
WordConverter.cs and the latest version of this tutorial can be found on the Muhimbi
website
.
59
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 53 of 60
Exception handling
Although you can let exceptions bubble up, we recommend catching any exceptions,
inspecting the root cause of the problem and then throwing a specific
WebServiceInternalException using one of the following exception types.
public enum WebServiceExceptionType
{
/// <summary>
/// Unknown error
/// </summary>
Unknown,
/// <summary>
/// File format not supported
/// </summary>
FileFormatNotSupported,
/// <summary>
/// File corrupt
/// </summary>
CorruptDocument,
/// <summary>
/// An error occurred while opening the file
/// </summary>
ErrorOpeningFile,
/// <summary>
/// Conversion process timeout
/// </summary>
ConversionTimeOut,
/// <summary>
/// Application hang. Can happen when document is password protected
/// </summary>
ConverterNotResponding,
/// <summary>
/// The underlying converter has not been installed or not correctly installed.
/// </summary>
ConverterNotInstalled,
/// <summary>
/// Internal Validation (Should only happen during development)
/// </summary>
InternalError,
/// <summary>
/// The specified output format is not supported (e.g. XPS output for HTML
/// conversion)</summary>
OutputFormatNotSupported
/// <summary>
/// Configuration file is invalid, e.g. no steps defined in a multi step converter
/// </summary>
ConfigurationError,
/// <summary>
/// The trial has expired (e.g. when processing non-PDF files)
/// </summary>
TrialExpired,
/// <summary>
/// Problem in external dependency, e.g. Ghostscript not installed or
/// wrong version.
/// </summary>
ExternalDependencyError
5
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 54 of 60
}
53
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 55 of 60
Appendix - Invoke 3
rd
party Converters
The PDF Converter has had the ability to add custom converters for a while
(See Appendix - Creating Custom Converters). However, although these plug-
ins work very well, if you are not a developer, or you are not familiar with .net
based development, then implementing a custom converter may be less than
trivial.
As of version 6.1 it is possible to use existing command line based 3
rd
party
conversion engines using the new Command Line Converter.
The latest version, and further details, of this topic can be found in this post on
our Blog
. A number of examples can be found in our Knowlede Base
.
The Command Line Converter is very simple to setup as you can see in the
following config file fragment for Siemens Teamcenter:
<add key="CommandLineConverter"
description="Converts using 3rd party executables"
fidelity="Full"
supportedExtensions="hp,hpg,hpgl,hpgl2,plt,cgm,mlr"
supportedOutputFormats="pdf"
type="Muhimbi.DocumentConverter.WebService.CommandLineConverter,
Muhimbi.DocumentConverter.WebService, Version=1.0.1.1, Culture=neutral,
PublicKeyToken=c9db4759c9eaad12"
parameter="c:\splm\vis20072\VVCP\prepare.exe | -PDF {0} -combine -page all
-out {1} –overwrite -size {Parameter1}"/>
The parameters are as follows:
1. key: Give the converter a unique name in case multiple Command Line
Converters are in use. Otherwise accept the default value.
2. description: The description of the converter exposed via the web
services API. As, for example, displayed in our SharePoint Central
Administration screen.
3. supportedExtensions: A list of input file formats supported by this
converter.
4. supportedOutputFormats: The file formats the converter can generate.
This is not limited to just PDF as our software fully supports cross-
conversion.
5. type: Do not touch.
6. parameter: The location of the 3rd party converter and the arguments to
send to it. Note that these 2 values are separated by a vertical pipe
character ‘|’. The arguments section supports the following parameters:
o
{0}: This will automatically be replaced with the full path to the input
file.
o
{1}: This will automatically be replaced with the full path and filename
where the output file should be generated.
14
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 56 of 60
o
{Parameter1}, {Parameter2}….{Parameter10}:
Optional parameters
that can be passed in via the web services interface
using ConverterSpecificSettings_CommandLineConverter. Use this to
pass proprietary information to the third party converter such as page
size or special processing instructions.
Once everything has been configured, all mapped file formats will be picked
up automatically and treated exactly the same as all other file formats
supported by the Muhimbi PDF Converter.
88
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 57 of 60
Appendix - Relevant articles on the Muhimbi Blog
The Muhimbi Blog
is updated frequently with new articles related to this
product. The following posts are relevant to readers of this Administration
Guide.
Troubleshooting steps for the PDF Converter.
Troubleshooting InfoPath to PDF Conversion / Document Converter Architecture.
Performance metrics for the Muhimbi PDF Converter
Enable SSL/HTTPS Communication in the Muhimbi Conversion Service
Convert Office files to PDF Format from .NET using a Web Service
Invoking the PDF Converter Web Service from Visual Studio 2005 using vb.net
Convert files to PDF Format from Java using Web Services
(WSImport)
Convert files to PDF Format from Java using Web Services
(Axis2)
Convert files to PDF Format from PHP using a Web Services based interface
Convert files to PDF Format from Ruby using a Web Services based interface
Set PDF Version, enable Fast Web Views, embed / strip fonts
Specifying PDF Viewer Preferences
Converting and merging multiple files using Web Services
(.NET)
Converting and merging multiple files using Web Services
(Java)
Splitting PDF Files using the PDF Converter Web Service and .NET / C#
Using Windows Azure to convert documents to PDF format
Adding custom Converters to Muhimbi’s range of PDF Conversion products
Using the awesome new watermarking features of the Muhimbi PDF Converter
Services
Using the PDF Watermarking features from Java based environments
Converting InfoPath forms including all attachments to a single PDF file
Controlling which views to export to PDF format in InfoPath
Dealing with hyperlinks when converting InfoPath files to PDF format
Convert InfoPath to MS-Word, Excel, XPS and PDF
Convert between document types (xls to xslx, doc to docx, xls to doc)
Convert HTML pages to PDF format
Convert AutoCAD (DXF, DWG) files to PDF
Using Third Party AutoCAD Converters
Convert MicroStation DGN files to PDF
Convert TIFF files to PDF
Convert any file format to TIFF
Convert PCL files to PDF
Convert legacy files formats (Lotus Manuscript, DisplayWrite, Wordstar etc)
Convert Outlook MSG files to PDF including all attachments
PDF/A Support in the Muhimbi PDF Converter Services & SharePoint
OCR Facilities provided by Muhimbi’s server based PDF Conversion products
Converting PDF document to PDF/A1b using a Web Service
Reduce PDF Converter Web Service message size using MTOM
47
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 58 of 60
A number of articles written for SharePoint based environments are available
as well.
Tuning SharePoint’s workflow engine
Using the PDF Converter from a SharePoint Designer workflow
Convert and merge multiple PDF files using a SharePoint Designer workflow
Converting multiple SharePoint files to PDF Format using Nintex workflow
Watermark PDFs using Nintex Workflow
Secure PDFs using Nintex Workflow
Convert and Merge PDFs using Nintex Workflow
Convert HTML to PDF using Nintex Workflow
Inserting SharePoint List data into a PDF document using a workflow
Configure PDF Security from a SharePoint Designer Workflow
Watermarking features of the Muhimbi PDF Converter for SharePoint
Applying user specific watermarks when a PDF document is opened
Merging dynamic data into watermarks using the PDF Converter for SharePoint
Use SharePoint Workflows to inject JavaScript into PDFs and prin
t the ‘open date’
Automatically convert files to PDF using an e-mail enabled Document Library
Batch print InfoPath Forms using the PDF Converter for SharePoint
Using SharePoint Forms Services to convert InfoPath forms to PDF format
Convert SharePoint HTML pages to PDF format
Converting SharePoint Lists to PDF format using a SharePoint Designer Workflow
Convert and merge files to PDF using the SharePoint User Interface
72
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 59 of 60
Appendix - Licensing
All Muhimbi products are licensed in a way that allows maximum flexibility.
Please familiarise yourself with the licensing agreement, particularly section 3
–
Grant of License, before purchasing our software.
For details see:
1. How many servers to purchase licenses for:
http://support.muhimbi.com/entries/21266472-How-many-servers-do-I-
need-to-be-licensed-for-
2. How we license:
http://blog.muhimbi.com/2010/01/how-we-license-our-products-make-
sure.html
3. The License Agreement:
http://www.muhimbi.com/Software-License-Agreement.aspx
4. Licensing FAQ:
http://support.muhimbi.com/entries/21266482-where-can-i-find-details-
about-pricing-and-licensing
In summary we support the following license types. Please refer to the
resources above for exact details:
Number of
servers
Unlimited
Web
Applications
Unlimited
Web
Farms
Unlimited
Locations
Redis-
tributable
Includes
Source
code
Server License
1
Enterprise License
Unlimited
OEM License
Unlimited
Source Code
License
Unlimited
Please note that some older SharePoint specific license types have been
discontinued. However, these are still valid for those customers that have
purchased them in the past. Please see the License Agreement for details
about these old style licenses.
1.
Free evaluation version: If you install the software without a license you
are using the evaluation version. The software is fully functional without
any time limits, but an evaluation message will be displayed on most
screens, in the workflow history and in any generated document. Please
do not use any evaluation software in your production environment. You
can get support using any of the means in the Support area on our
website.
42
PDF Converter Services - Installation & Administration Guide
PDF Converter Services - Installation & Administration Guide - Version 8.0 - 03/12/15
© Copyright 2015, Muhimbi Ltd
Page 60 of 60
2.
Server License: The easiest way to license our software is to buy a
Server License for each of your servers, virtual or physical, that runs our
software.
3.
Enterprise License: If you are running our software on more than a
handful of servers then it may be more economical to purchase an
Enterprise License. This allows the software to be installed on an unlimited
number of servers in the organisation.
4.
OEM License: If you wish to bundle our software with your own solution
and redistribute it to 3
rd
parties then you require an OEM License. Please
read the details in the Software License Agreement for more information.
5.
OEM License + Source Code: If you need all the benefits of the OEM
License and / or you need access to the source code to make
modifications specific to your organisation, then this license type is the
best option. Note that we do not provide support for our software once
changes have been made to the source code. Please read the details in
the Software License Agreement if you want to bundle our software with
your own solution.
The PDF Converter for SharePoint license is limited to use from SharePoint
environments only. If you wish to invoke the PDF Conversion Service from a
non-SharePoint based environment, e.g. Java, .NET or any other Web
Services capable system then you will need to purchase a license for the PDF
Converter Services.
The PDF Converter Professional license is an add-on that adds additional
functionality to either the PDF Converter for SharePoint or the PDF Converter
Services. This functionality, e.g. PDF/A post-processing and OCR, is usually
associated with more complex environments and has therefore been
separated from the main product. Please note that the PDF Converter
Professional is a license that must be applied alongside a valid license of the
PDF Converter for SharePoint or PDF Converter services
. A separate
download of the Professional version of the software is not needed, the
license unlocks all functionality.
Documents you may be interested
Documents you may be interested