View source for Configuring Doc2Any in LogicalDOC with Microsoft Office

= Configuring Doc2Any in LogicalDOC to Use Local Microsoft Office for High-Fidelity PDF Conversion =

== Overview ==

LogicalDOC supports '''Doc2Any''' as an '''external document conversion engine''' for previews and PDF generation.  
Doc2Any is '''not bundled or shipped with LogicalDOC''': LogicalDOC declares compatibility with it and can invoke it as an external converter once properly installed and configured.

Doc2Any supports a wide range of document formats and, when configured to use a '''locally installed Microsoft Office instance''', provides the '''highest fidelity PDF output and Word document previews''', especially for complex layouts.

To use Doc2Any with LogicalDOC:

* Doc2Any must be '''downloaded separately''' from the manufacturer’s website
* The converter must be '''installed locally''' on the LogicalDOC server
* LogicalDOC must be configured to invoke Doc2Any as an external tool

In this guide, for consistency, the Doc2Any package (typically distributed as a <code>.zip</code> archive) is assumed to be extracted to:

<syntaxhighlight lang="text">
C:\LogicalDOC\doc2any_cmd
</syntaxhighlight>

---

== Prerequisites ==

Before starting, ensure the following requirements are met:

* LogicalDOC installed on '''Windows'''
* '''Doc2Any downloaded and installed separately'''
** Extracted to <code>C:\LogicalDOC\doc2any_cmd</code>
* Microsoft Office (Word) installed '''locally on the same machine'''
* A Windows user account:
** Associated with a '''valid Microsoft Office license'''
** Logged in at least once (profile initialized)
* Administrative access to:
** LogicalDOC Administration panel
** Windows Command Prompt (Run as Administrator)
** Windows Task Scheduler

---

== Step 1 – Configure Doc2Any in LogicalDOC ==

Navigate to:

'''Administration → Import and Export → Format Converters'''

In the ''Associations'' section, verify or create the following mapping:

* '''Input:''' <code>docx</code>
* '''Output:''' <code>pdf</code>
* '''Converter:''' <code>DocToAnyConverter</code>

[[File:logicaldoc-doc2any-format-converter-settings.png|600px|thumb|LogicalDOC – Doc2Any format converter configuration]]

=== DocToAnyConverter Parameters ===

Select '''DocToAnyConverter''' and configure the parameters as follows:

{| class="wikitable"
! Parameter
! Value
|-
| path
| <code>C:\LogicalDOC\doc2any_cmd\doc2any.exe</code>
|-
| licenseKey
| ''Your Doc2Any license key''
|-
| useOffice
| <code>true</code>
|-
| usePrinter
| <code>false</code>
|-
| runViaService
| <code>true</code>
|}

'''Notes:'''

* <code>useOffice=true</code> forces Doc2Any to use Microsoft Word instead of LibreOffice
* <code>runViaService=true</code> enables execution via a background service
* <code>usePrinter=false</code> avoids dependency on printer drivers

---

== Step 2 – Whitelist Executables (allowed-commands.txt) ==

LogicalDOC restricts execution of external programs for security reasons.  
All Doc2Any-related executables must be explicitly whitelisted.

Edit the file:

<syntaxhighlight lang="text">
<LogicalDOC installation directory>\conf\allowed-commands.txt
</syntaxhighlight>

Add or verify the following entries (adjust paths if needed):

<syntaxhighlight lang="text">
C:\LogicalDOC\doc2any_cmd\doc2any.exe
C:\LogicalDOC\ghostscript\bin\gs.exe
C:\LogicalDOC\imagemagick\convert.exe
C:\Program Files\Eclipse Adoptium\jdk-21.0.4.7-hotspot\bin\keytool.exe
C:\LogicalDOC\openssl\bin\openssl.exe
C:\LogicalDOC\clamav\clamscan.exe
</syntaxhighlight>

[[File:allowed-commands.png|600px|thumb|allowed-commands.txt with Doc2Any executables]]

---

== Important Note – LogicalDOC-Provided Service Files ==

The following files are '''not part of the standard Doc2Any distribution''' and are '''not provided by the Doc2Any vendor''':

* <code>docPrint_Service.xml</code>
* <code>register-docPrint_Service.bat</code>
* <code>register-docPrint_ServiceXML.bat</code>

These files are '''provided by LogicalDOC''' and are required to integrate Doc2Any with Microsoft Office using a Windows Scheduled Task.

They implement the execution model expected by LogicalDOC when the <code>runViaService=true</code> parameter is enabled.

---

=== Installation Location ===

All three files must be copied to the following directory:

<syntaxhighlight lang="text">
C:\LogicalDOC\doc2any_cmd\doc2any_service
</syntaxhighlight>

This directory is referenced by the Doc2Any configuration and by the registration scripts.

---

=== Purpose of the Files ===

{| class="wikitable"
! File
! Purpose
|-
| <code>docPrint_Service.xml</code>
| Defines the Windows Scheduled Task used to run Doc2Any in background mode
|-
| <code>register-docPrint_Service.bat</code>
| Registers the scheduled task using inline parameters
|-
| <code>register-docPrint_ServiceXML.bat</code>
| Registers the scheduled task using the XML definition (recommended)
|}

The XML-based approach is preferred because it allows:
* consistent task configuration
* explicit privilege control
* reliable startup behavior
* better long-running process handling

---

=== Downloading the Files from the Wiki ===

For convenience, these files can be made available directly from this Wiki page.

Example:

* [[Media:docPrint_Service.xml|Download docPrint_Service.xml]]
* [[Media:register-docPrint_Service.bat|Download register-docPrint_Service.bat]]
* [[Media:register-docPrint_ServiceXML.bat|Download register-docPrint_ServiceXML.bat]]

After downloading, copy the files into:

<syntaxhighlight lang="text">
C:\LogicalDOC\doc2any_cmd\doc2any_service
</syntaxhighlight>

and continue with the configuration steps described below.

---

=== Why These Files Are Distributed Separately ===

Doc2Any is a generic document conversion engine, while LogicalDOC defines a specific and supported integration model for running Microsoft Office in background mode.

Providing these files separately allows LogicalDOC to:

* control the execution context
* comply with Microsoft Office automation constraints
* maintain compatibility across Doc2Any versions
* update integration logic independently from Doc2Any releases


== Step 3 – Edit the Service Registration Script (Mandatory) ==

Microsoft Office automation '''must run under a real Windows user account''' associated with the Office license.

Before registering the service, edit:

<syntaxhighlight lang="text">
C:\LogicalDOC\doc2any_cmd\doc2any_service\register-docPrint_ServiceXML.bat
</syntaxhighlight>

Locate the placeholder string:

<syntaxhighlight lang="text">
runasuser
</syntaxhighlight>

Replace it with the '''exact username''' of the Windows account to which Microsoft Office is licensed.

=== Example ===

If Office is licensed to the user <code>docprint</code>, replace:

<syntaxhighlight lang="text">
runasuser
</syntaxhighlight>

with:

<syntaxhighlight lang="text">
docprint
</syntaxhighlight>

'''Important:'''

* The user must already exist
* The user must have logged in at least once
* Microsoft Office must be activated for this user

---

== Step 4 – Register the DocPrint Background Service ==

Doc2Any uses a '''Windows Scheduled Task''' (not a classic Windows service) to run Microsoft Office reliably in background mode.

=== Open an Elevated Command Prompt ===

[[File:windows-command-prompt.png|600px|thumb|Command Prompt – Run as Administrator]]

---

=== Run the Registration Script ===

<syntaxhighlight lang="bat">
cd C:\LogicalDOC\doc2any_cmd\doc2any_service
register-docPrint_ServiceXML.bat
</syntaxhighlight>

During execution:

* You will be prompted for the password of the specified Windows user
* The scheduled task '''docPrint_Service''' will be created

---

== Step 5 – Verify the Task Scheduler Configuration ==

Open '''Task Scheduler''' and locate:

<syntaxhighlight lang="text">
Task Scheduler Library → docPrint_Service
</syntaxhighlight>

[[File:docPrint_Service-in-windows-task-scheduler.png|600px|thumb|docPrint_Service in Windows Task Scheduler]]

=== General Tab ===

* Run whether user is logged on or not
* Run with highest privileges

---

=== Triggers Tab ===

* Trigger: '''At system startup'''

---

=== Settings Tab (Critical) ===

[[File:task-settings-disable-stop-long-tasks.png|600px|thumb|Task settings preventing forced termination]]

Configure:

* Allow task to be run on demand
* Do '''not''' stop the task if it runs longer than a set time
* Do '''not''' restart the task on failure
* Force stop only if explicitly requested
* If the task is already running, '''do not start a new instance'''

These settings prevent:

* Premature termination of long conversions
* Multiple Office instances
* PDF generation failures

---

== Step 6 – Restart and Test ==

# Restart the LogicalDOC service
# Upload a DOCX document with complex formatting
# Open the preview
# Download the generated PDF

If correctly configured:

* PDF output matches Microsoft Word exactly
* Previews are stable
* No conversion errors appear in logs

---

== Why a Scheduled Task Is Used ==

Microsoft Office applications are '''not designed to run as Windows services'''.

Using a Scheduled Task provides:

* Proper user context
* Access to Office COM components
* Stable automation
* Compliance with Microsoft support guidelines

---

== Conclusion ==

By installing Doc2Any externally, configuring LogicalDOC to invoke it correctly, and running Microsoft Office through a dedicated Windows background task, LogicalDOC can deliver:

* High-fidelity PDF conversions
* Accurate Word previews
* Reliable production-grade behavior

This configuration is '''strongly recommended''' for enterprise environments where document accuracy is critical.