95
3-Heights™ Document Converter, Version 4.6
Page 2 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
Table of Contents
1
Introduction .......................................................................................... 4
1.1
Product Editions ...................................................................................... 4
1.1.1
Enterprise Edition ............................................................................. 5
1.1.2
Small-Medium Enterprise Edition (SME) ............................................... 6
1.1.3
Desktop Edition ................................................................................ 6
1.2
Applications ........................................................................................... 6
1.2.1
Online Applications............................................................................ 6
1.2.2
Batch Processing .............................................................................. 7
1.2.3
Archiving ......................................................................................... 7
1.2.4
Document Assembly and Publishing .................................................... 7
1.3
Features ................................................................................................ 7
2
Installation ............................................................................................ 9
2.1
Platform Requirements ............................................................................ 9
2.2
Platform Preparation ............................................................................. 10
2.3
Installing the 3-Heights™ Document Converter......................................... 12
2.3.1
Common Procedure for Server or Client ............................................. 12
2.3.2
Server Installation .......................................................................... 14
2.3.3
Installation Parameters .................................................................... 15
2.3.4
Post Installation Procedure for Server Components ............................. 16
2.3.5
Post Installation for Client Components ............................................. 20
2.4
Quick Service Installation on a Client PC .................................................. 23
2.5
Updating an Existing Installation ............................................................. 23
2.5.1
Uninstallation Checklist .................................................................... 23
2.5.2
Re-Installation Checklist .................................................................. 24
3
Using the Document Converter ............................................................ 25
3.1
Explorer Shell Extension ........................................................................ 25
3.1.1
Using the Shell Pop-up .................................................................... 25
3.1.2
Configuration of the Pop-up Menu ..................................................... 26
3.2
Watched Folders ................................................................................... 26
3.3
Command Line Executable ..................................................................... 26
3.4
Office Add-In ........................................................................................ 27
3.4.1
Configuration ................................................................................. 27
3.4.2
Installation for 64-Bit Office ............................................................. 27
3.4.3
Using the Office Add-In ................................................................... 27
4
Configuration ....................................................................................... 29
4.1
Conversion Control................................................................................ 29
4.2
O2PSRV.exe.config ............................................................................... 40
4.3
O2PWSC.exe.config ............................................................................... 43
4.4
O2PWFS.exe ........................................................................................ 43
4.4.1
O2PWFS.ini .................................................................................... 44
4.4.2
Implementation Limits ..................................................................... 45
4.5
Mail Folder Service ................................................................................ 46
4.5.1
O2PMFS.ini .................................................................................... 46
4.5.2
Requirements and Limitations .......................................................... 46
5
Reference Manual ................................................................................ 47
76
3-Heights™ Document Converter, Version 4.6
Page 3 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
5.1
Document Type Index ........................................................................... 47
5.2
Document Extensions Index ................................................................... 47
5.3
Processing Paradigm ............................................................................. 48
5.4
Conversion Jobs.................................................................................... 49
5.4.1
API ............................................................................................... 49
5.4.2
Command Line Executable ............................................................... 61
5.4.3
Watched Folder Service ................................................................... 62
5.4.4
Stamping ....................................................................................... 63
5.4.5
Document Transformations .............................................................. 64
5.5
Optimization ........................................................................................ 64
5.6
Architecture Background ........................................................................ 65
5.7
Plug-ins ............................................................................................... 66
5.7.1
ScriptPlugin DLL ............................................................................. 67
5.7.2
NetPlugin DLL ................................................................................. 67
5.8
Debugging ........................................................................................... 67
5.8.1
Debugging of the Dispatcher Service ................................................. 67
5.8.2
Debugging of Worker Sessions ......................................................... 69
5.8.3
Options ......................................................................................... 70
5.9
PDF/A.................................................................................................. 70
5.10
Security Considerations ......................................................................... 71
5.11
Configuration Background Information .................................................... 71
5.11.1
TIFF Output Format......................................................................... 72
5.11.2
Conversion of Internet Mail Messages ................................................ 73
5.11.3
HTML Conversion ............................................................................ 74
5.12
Platform Issues .................................................................................... 75
5.13
Configuration of Terminal Services on Windows 2008 Server ...................... 76
6
Troubleshooting Tips ........................................................................... 82
7
Samples ............................................................................................... 86
7.1
Command Line Tool .............................................................................. 86
7.2
C API .................................................................................................. 86
7.3
C#.NET ............................................................................................... 87
7.4
Visual Basic Script................................................................................. 87
7.5
Java .................................................................................................... 88
7.5.1
Microsoft.NET based Java API ........................................................... 88
7.5.2
Web Service Interface ..................................................................... 88
7.5.3
Using MTOM with the Web Service .................................................... 90
25
3-Heights™ Document Converter, Version 4.6
Page 4 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
1
Introduction
The 3-Heights™ Document Converter constitutes a solution for converting a wide range
of document formats to PDF or TIFF. It can create PDF/A-1 and PDF/A-2 compliant files
from office documents, images, or just simple text files.
The Document Converter supports various document formats and also includes support
for unpacking and processing e-mail attachments and ZIP or RAR archives that may be
nested in arbitrary depth.
The main purpose of this product is to help you:
making documents archivable (especially MS Office documents)
migrating existing archives
exchanging documents
fulfilling standards (ISO) and security requirements
archiving websites and e-mail
standardizing the variety of formats across the corporation
1.1
Product Editions
The Document Converter comes in three different editions. Each edition is intended for a
certain purpose. The generic product overview and evaluation-versions can be found on
the web at:
https://www.pdf-tools.com/pdf/Document-Converter-Service.aspx
92
3-Heights™ Document Converter, Version 4.6
Page 5 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
If you are in doubt which version is best for you, please feel free to contact the PDF
Tools pre-sales team.
http://www.pdf-tools.com/pdf/Corporate/Contact.aspx
Enterprise
Edition
SME Edition
Desktop
Edition
Operation Systems
Server
Windows Server
2008, 2008-R2,
2012
Windows Server
2008, 2008-R2,
2012
Windows Server
2008, 2008-R2,
2012
Client
Windows Vista or
newer
Unix system (via
web-service)
Windows Vista or
newer
Windows Vista or
newer
Terminal Server
Required1
Formats
Office, Text
Yes
Yes
Yes
PDF, Images
Yes
Yes
Yes
E-Mail with Attachments
Yes
Yes
Website
Yes
Yes
Containers (e.g. ZIP)
Yes
Yes
Yes
Custom (e.g. CAD)
Yes
eatures
Application/Interfaces
Watched folders
Shell
extension
for Explorer
Watched
e-mail
folders via IMAP
API
Web-service
Shell
Watched folders
Shell extension
for Explorer
API
Shell
Interactive
PDF/A-1, PDF/A-2
Yes
Yes
Yes
TIFF Output
Yes
Yes
Load-Balancing
Yes
OCR
Optional
Optional
Optional
1.1.1 Enterprise Edition
This is the full-featured server-based solution for automated document conversion. It
can be embedded in various ways into existing systems or be used to create a new
conversion process. It provides all features described in this documentation, such as a
watched folder service, a shell interface for batch jobs, a shell extension to right-click a
1 may include terminal server licenses
40
3-Heights™ Document Converter, Version 4.6
Page 6 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
document in Windows Explorer and convert to PDF, API (C/C++, .NET, COM, Java),
web-service and load-balancing.
The Enterprise Edition is meant for medium to large corporations and/or situations
where high throughput is needed. It requires a Windows Server operating system.
For the installation it is required to have knowledge on Windows Server environments.
For the configuration, it is preferable to have knowledge on PDF and PDF/A. A software
engineer may be required when using the API and make use of the full potential of the
product.
This documentation is intended for the Enterprise Edition and to some extent for the
SME Edition. Its latest version of this manual can be found on the web at:
https://www.pdf-tools.com/public/downloads/manuals/dcve.pdf
There is a separate API documentation available for the .NET interface:
https://www.pdf-tools.com/public/downloads/manuals/dcve_api.pdf
1.1.2 Small-Medium Enterprise Edition (SME)
The SME Edition is a stripped-down and therefore easier to use version of the Enterprise
Edition. It does not provide an API, website-archiving or load-balancing. Its main
purpose is document conversion using watched folders. Many features, especially the
watched folder configuration, described in this documentation apply to the SME Edition.
The SME Edition is intended to be installed and configured by a system administrator
who has knowledge about PDF and PDF/A.
There is a separate installation and configuration documentation available for the SME
Edition, which can be used as a quick-start.
https://www.pdf-tools.com/public/downloads/manuals/dcvm.pdf
1.1.3 Desktop Edition
This edition is for interactive use only. It is a separate desktop-tool and has nothing in
common with respect to installation, configuration and use with other editions. However,
the resulting PDF/A documents are equal to the other editions.
Its documentation can be found here:
https://www.pdf-tools.com/public/downloads/manuals/dcvd.pdf
1.2
Applications
The 3-Heights™ Document Converter addresses applications that are in need of
automated document conversion.
1.2.1 Online Applications
Online applications as well as interactive clients make use of the Document Converter to
provide document conversion on-the-fly. Typical documents are processed in only a few
39
3-Heights™ Document Converter, Version 4.6
Page 7 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
seconds to be presented to the users. There is no need to set up any infrastructure on
the client side, making deployment as easy as possible.
1.2.2 Batch Processing
Batch processing is supported in several ways by the Document Converter. A convenient
way to handle conversion batches is via so called “watched folders”. Input documents
just need to be copied into a dedicated folder to be automatically processed, with the
output documents created in the configured output folder.
Even more flexibility is available by integrating the service into application specific
scripts or command files.
1.2.3 Archiving
The 3-Heights™ Document Converter is a great tool for archiving mixed collections of
office documents, including e-mail with attachments. It also accepts ZIP or RAR
archives, and produces a single PDF/A-1 or PDF/A-2 conforming document containing
the whole collection of input documents converted to PDF.
1.2.4 Document Assembly and Publishing
The capability to convert and assemble documents can also serve to assemble multiple
documents into one and prepare it for distribution.
1.3
Features
The 3-Heights™ Document Converter combines the features of the 3-Heights™ PDF
Producer driver for Windows and the various document authoring applications such as
Microsoft Word, Excel, PowerPoint, Visio, etc.
The most significant features include
• Robust client/server architecture
• Scalability for high throughput by parallel processing
• Quick and easy installation (MSI Installer)
• Configuration application for easy management of conversion settings
• Minimal platform and resources requirements for clients
• Convenient integration into user environment via explorer pop-up menu
• Automatic conversion processing from watched folders
• Automatic processing also from folders on an e-mail server
• Additional input document formats available via plug-ins
• Application Programming Interfaces available (C/C++, Java, COM)
• Support for multiple office application versions
• The document applications and formats currently supported are
21
3-Heights™ Document Converter, Version 4.6
Page 8 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
• Microsoft Office, including Word, Excel, PowerPoint, Visio, Outlook
• Versions 11 or later (MS Office 2003, 2007, 2010, 2013); recommended version is
MS Office 2010 (64 bit)
• Document formats corresponding to the installed MS Office version
• MS Word accepts non-native formats, such as plain text (ASCII and UNICODE),
WordPerfect, HTML and others.
• The only MS Outlook format currently supported are .MSG files; these may contain
any content that Outlook can display and print; attachments are extracted and
converted as well
• PDF (Portable Document Format)
• EML (Internet Mail Message format, as exported e. g. from Outlook Express)
• Image Documents (TIFF, JPEG, BMP, PNG, GIF, JBIG2, JP2, JPM)
• ZIP or RAR files containing documents corresponding to any supported format
• Output as PDF: PDF/A-1b, PDF/A-1a, PDF/A-2b, PDF/A-2u, PDF/A-2a, PDF/A-3
(a,u,b)
• Output as TIFF: Bi-tonal, Monochrome, Color; with CCITT G4, JPEG, flate, LZW or
no compression
72
3-Heights™ Document Converter, Version 4.6
Page 9 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
2
Installation
This chapter guides you through the installation of the 3-Heights™ Document Converter.
If you want to install the product on a non-server platform for evaluation purposes,
please refer to section 2.4.
2.1
Platform Requirements
The hardware and software resources required for proper operation of the Document
Converter depend on the type of input documents and processing options used. The
following table lists typical scenarios with recommended minimum resources:
Disk
Memory
CPUs
TS1
Sessions
Small Office Documents, low throughput (<1
page per second average)
100
MB
512 MB
2
1
Small Office Documents, higher throughput
(several pages per second average)
200
MB
1-2 GB
4
2-4
Complex Documents
200
MB
1-2 GB
2
1
Raster image based documents for conversion
with OCR recognition; moderate throughput;
OCR Service on separate Computer
200
MB
512 MB
2
1
OCR Service platform (per 2 CPU OCR license)
200
MB
512 MB
2
0
1 (TS) Terminal Server sessions are required to make use of concurrent processing by multiple
instances of Office applications, such as Microsoft Word, Excel or PowerPoint.
In addition to the resources listed above, add the disk space requirements for any office
applications you need to install to support the corresponding source document formats.
As you may have noticed from the table above, the following factors and parameters are
involved:
Disk space usually is not an issue. The Document Converter installation is small, and
disk space is determined mainly by space requirements for storing log files and
temporary files.
Memory requirements are mostly determined by the type of conversions involved. Office
applications may demand a significant amount of memory when source documents are
large or complex. Another reason for high memory demand can be e.g. high resolution
PDF to TIFF conversion (that is performed natively by the Document Converter).
Configuring multiple worker sessions will also require more memory, as each session will
occupy a certain amount of memory (which can vary from a few MB to several 100 MB
depending on the type of documents being processed).
The CPU load depends on one hand on the configured degree of concurrency (number of
worker sessions) and the conversion load on the service. On the other hand, certain
types of processing impose excessive CPU load by their nature, such as OCR processing
46
3-Heights™ Document Converter, Version 4.6
Page 10 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
and image (re-)compression. As a rule of thumb, one extra CPU per additional worker
session is sufficient, because most office applications will not make use of more than
one CPU core in any circumstances.
2.2
Platform Preparation
Please use the following check list for making sure your platform is prepared for the
installation of the 3-Heights™ Document Converter. A more comprehensive description
of the preparation steps follows the checklist.
1 Windows 2008 Server or higher2 installed (Standard Edition, English or
German); Internet Explorer: see foot note 3
2 Microsoft.NET 4.0 (should be automatically installed with Windows Server
2012)
3a Enable Remote Desktop connections (Control panel, System Properties,
Remote tab)
3b Verify terminal services related security settings (“Local Policies”, “user rights
assignments”, permit “Allow log on through Terminal Services”)
4 Install Microsoft Office 2010, or 2013 (select features as appropriate, leaving
away unnecessary gadgets; install complementary add-ons as required; install
Service Packs)
5 Create service accounts for worker sessions
6 Log in to each of the service accounts via Remote Desktop (mstsc.exe); start
each Office application and verify options and supported document formats
(for details, see below)
7 Optional: install Adobe Reader, version 10 or later. This is not only useful to
view converted PDF documents on the server, but also enables the converter
service to process PDF forms based on XFA that need rendering.
Perform standard installations for the Windows operating system. PDF Tools supports
Windows 2008 Server through Windows 2012 Server R2 in English and German.
The use of other configurations is possible, but PDF Tools will not be able to provide
support for platform related issues.
Make sure the full Microsoft.NET 4.0 Framework or newer is installed.
Unless Terminal Services are configured in Application Server mode, verify that
Remote Desktop connections are enabled on the server (under Control panel, System
Properties, Remote tab). Refer to section 5.13 “Configuration of Terminal Services on
Windows 2008 Server” for details.
Configure at least one service user account for the Document Converter. This can be a
local account or an ordinary domain user account. In any case, make sure the user is
2
See 5.12 Platform Issues for a short discussion of these platforms
3
Internet Explorer may be relevant, if the web site archiving feature shall be used or for
converting HTML bodies of emails
Documents you may be interested
Documents you may be interested