Convert Microsoft Office files
The Conversion Service uses Microsoft Office applications to process jobs containing Word, Excel, and PowerPoint documents. Select one of the following two options when configuring the Microsoft Office file conversion in the Conversion Service Configurator:
- Conversion with a local Microsoft Office installation on the same server.
- Conversion using the Office for the web service.
These options differ in configuration parameters, output quality, and performance. Both options extract embedded documents from Office documents in Open XML format (for example, DOCX, XLSX, PPTX) in a destructuring step before conversion. Macro instructions are disabled in all cases.
Choose a Microsoft Office conversion method
To ensure high-quality conversion with accurate layout and visual fidelity, the Conversion Service offers two Microsoft-based processing options: a local Microsoft Office installation or the Office for the web service in Microsoft Azure Cloud. Both options deliver equally high conversion quality, with no significant differences identified in detailed comparisons.
Use the local Microsoft Office installation if you:
- Require high performance. Cloud conversion may involve significant overhead for uploading and downloading file contents.
- Need to convert large documents (more than 100 MB).
- Want to process many large Excel files.
- Only the local installation option supports fit to page in Microsoft Excel.
- Microsoft Excel files with many sheets or hundreds of pages aren't supported in the Office for the web service.
- Must repair Word documents.
- Work with password-protected documents.
- Handle macro-enabled files (XLTM, PPTM, WordML).
- Need to use special or custom fonts.
- Fonts can be installed locally but not added to the web service.
- The web service includes more default fonts than a typical Windows server.
- Keep data on-premises if required by security policies or if you require a lack of internet access.
- Web service conversions temporarily store files in the Azure cloud. Storage region depends on your subscription.
Use the Convert using the Office for the web service if:
- You're converting smaller files (smaller than 100 MB), especially Word documents.
- Files were created using Microsoft Office for the web.
- You're deploying the Docker version in production.
- You prefer lower setup and maintenance overhead.
Convert files using local Microsoft Office installation
To comply with Microsoft licensing, each client submitting Word, Excel, or PowerPoint jobs must be licensed for Microsoft Office. For more information, see Licensing Microsoft Office software in Commercial Licensing on the Microsoft site.
If you want to Convert files using local Microsoft Office installation, you must have a compatible version of Microsoft Office installed on the Conversion Service server:
Office version |
---|
Office 2019* (64-bit) |
Office 2021 (64-bit) |
Office 2024 (64-bit) |
Microsoft 365 (64-bit) |
* The Pdftools support for Microsoft Office 2019 will end in October 2025.
The supported language is English (United States). The Microsoft Print to PDF virtual printer must also be installed.
For optimal conversion results, use the same Microsoft Office version that was used to create the documents. The Conversion Service only supports Microsoft Office 2019 and later.
Install and configure local Microsoft Office installation
During Microsoft Office setup, follow these steps and requirements:
- Use a static license key (device-based license), especially with Microsoft 365. Avoid user logins to prevent dialog pop-ups that can interrupt processing.
- After installation, activate the Office license.
- Open sample Word, Excel, and PowerPoint files to confirm there are no blocking pop-ups.
- If your documents rely on language features like hyphenation, install the required language packs.
If Windows Defender is active, enabling the Windows Defender Rules setting in the Configurator may improve conversion speed. It adds exceptions for specific processes and folders to reduce scanning overhead.
Enable it under Conversion Service > Windows Defender Rules.
Make sure group policies don't override these exceptions.
Third-party tools like Bitdefender may block required operations. To guarantee successful conversion, you must add any application exceptions to your third-party antivirus software.
Set up on Windows
Assign a user account for the local Microsoft Office installation. You can either:
- Recommended: Use automatically generated user account
- Existing user account
Recommended: Use automatically generated user account
Unless restricted by security policies or domain controllers, let the Conversion Service Configurator create a ConvsrvOfficeUser
account with a secure password.
The following settings are applied automatically:
- Joins the
Users
group. - Has encrypted credentials saved through the Windows Data Protection API.
- Grants the user Allow log on locally and Log on as a batch job security policies.
- Has registry and DCOM permissions for Word, Excel, and PowerPoint.
To set up an automatically generated user account in the Configurator:
- In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
- Next to the Office Conversion, click Configure
- Select Local Office Installation and Automatically Create a User Account, and then click Next.
- Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.
- ConvsrvOfficeUser appears in the username field with a random password. Click Apply.
The automatically generated user account is recommended for most servers unless specific security policies or domain controller restrictions apply. This is the case if:
- Log on as a batch job security policy is applied.
- Allow log on locally security policy is applied.
- The server is managed by a domain controller.
Use an existing user account
Use this if your server has strict security rules or is managed through a domain controller.
Requirements:
- Create the user account manually (local or domain). The Conversion Service Configurator does not modify this account.
- Grant Allow log on locally and Log on as a batch job (or assign to a group with these rights).
- Don't assign admin privileges. Set up the user account with minimum user rights (don't assign the user account to the Administrators group).
- Update the configuration if the password changes or expires.
These properties and settings are set automatically:
- The password is encrypted using the Windows Data Protection API before it is stored in a configuration file.
- The registry and DCOM permissions for Word, Excel, and PowerPoint are adjusted.
If using a domain user, disable any group policies enforcing regular password changes. Otherwise, you'll need to reconfigure the Office setup each time the password changes.
To set up an existing user account in the Configurator:
- In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
- Next to the Office Conversion, click Configure
- Select Local Office Installation with an Existing User Account, and then click Next.
- Enter the username and password for the user account.
The Conversion Service accepts all standard formats for Windows users (both
Username@domain
anddomain\Username
formats). TheUsername
is automatically resolved toServerName\Username
. - Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.
Set up in Docker container
Send Office documents to another Conversion Service instance of the Conversion Service running on Windows. Office document conversion can be activated as follows:
-
Set up and run the service on Windows.
-
Enable Office Conversion in the Processing Steps section of your profile. Note that this is active by default.
-
When starting the Docker container, set the WINDOWS_SERVICE_ENDPOINT environment variable:
docker run -dp 13033:13033 ... \
-e WINDOWS_SERVICE_ENDPOINT=http://server:13033/conversion/v1.0/rest \
pdftoolsag/conversion-serviceNote that if the Windows service uses HTTPS, its host certificate must be trusted by the Docker container. Otherwise, no connection can be established. By default, no trusted certificates are installed.
-
Copy trusted certificates to /usr/local/share/ca-certificates/.
-
Run the command update-ca-certificates.
Convert using the Office for the web service
The Office for the web service option converts the documents using a Microsoft Azure Cloud service. Technologies used with this option include the Microsoft Authentication Library (MSAL), the Microsoft Graph API, and the Microsoft Sharepoint API.
The conversion flow:
- Upload the file to the user's OneDrive.
- Convert the file to PDF.
- Delete the uploaded file.
All connections use HTTPS. The service encrypts files before transmitting them over the internet.
You need a valid license to allow the Conversion Service to convert Word, Excel, and PowerPoint documents. This means you must have:
- Microsoft 365 for business subscription (Azure Cloud tenant) with a dedicated user account.
- Microsoft 365 license for this dedicated user.
You should create a dedicated user account, as full control over this user's OneDrive is requested.
Set up on Windows
Use the Configurator to set up the Office for the web:
- In the Conversion Service Configurator, go to Conversion Service tab, and then scroll to the Configuration section.
- Next to the Office Conversion, click Configure
- Select Office for the web, and then click Next.
- Enter the user account login (usually, an email address) for the Microsoft Office for the Web Service in the Username field.
- Click Apply, and then in the Changes detected dialog box, click Save & Restart Service.
- Sign in to the Microsoft 365 user account in the pop-up window that appears. Enter the password for the user account. If your company has set up 2-factor authentication, enter the authenticator code and click Verify.
Set up in Docker
- Enable Office Conversion in the Processing Steps section of your profile. Note that this option is active by default.
- Create a persistent volume (for example,
convsrv-etc
) to store the authentication token cache.docker volume create --name convsrv-etc
- Create the token cache directory and set permissions. Mount the volume, create the
TokenCaches
folder, and give the Conversion Service user read and write access.docker run --rm \
--mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
--user root pdftoolsag/conversion-service \
bash -c "mkdir /etc/convsrv/TokenCaches && chown convsrv:convsrv /etc/convsrv/TokenCaches" - Initialize the token cache by running the
csconfig
tool to:docker run \
--mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
-e SERVICE__OFFICE__TYPE=OfficeWebService \
-e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \
pdftoolsag/conversion-service \
bash -c "bin/csconfig office webinit" - To start the Docker container, mount the token cache volume and set the required environment variables.
Set environment variables SERVICE__OFFICE__TYPE and SERVICE__OFFICE__USERNAME according to the configured user and office type.
docker run -dp 13033:13033 \
--mount "type=volume,src=convsrv-etc,dst=/etc/convsrv" \
-e SERVICE__OFFICE__TYPE=OfficeWebService \
-e SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com \
pdftoolsag/conversion-service
Troubleshooting
You may encounter problems when setting up and using Office conversion. The issues can be divided into two categories:
Configuration errors
The following sections include the warnings and errors that you encounter inside the Configurator during configuration and possible solutions.
Microsoft Office is not installed
Click to expand for more details and solution:
3-Heights Document Converter installation detected
Click to expand for more details and solution:
User validation failed
Click to expand for more details and solution:
Trust relationship failed
Click to expand for more details and solution:
Office configuration problem in Configurator
Click to expand for more details and solution:
The user name or password is incorrect when using a domain user account
Click to expand for more details and solution:
The Office conversion suddenly stops working when using a domain user account. In this case, the error is usually caused by a password group policy that forces password change at a regular interval. You need to disable the group policy for that domain user.
Specific errors related to Word, Excel, and PowerPoint documents
The following sections include errors that are associated with the Microsoft Office application use.
The document is corrupt or a pop-up dialog window blocks the conversion process
Click to expand for more details and solution:
The application WINWORD exceeded the memory limit of 2048 MB
Click to expand for more details and solution:
Conversion of test.docx
to PDF failed COM Exception: (0x80004005)
Click to expand for more details and solution:
If this is the case, check:
- Windows Defender Rules are enabled in the Configurator.
- Any exceptions in the Windows Defender Rules are not forbidden by group policy
- Any exceptions are added to any third-party antivirus software (for example Bitdefender)
COM Exception: (0x800a18a0): You are attempting to open a file type xxx
that has been blocked by your File Block settings in the Trust Center.
Click to expand for more details and solution:
Excel conversion fails with a “Generic” error (COM exception 0x800a03ec)
Click to expand for more details and solution:
This error may be caused by the printer spooler or Microsoft Printer. The printer spooler is required for Office conversion.
If you encounter this error, check:
- The Printer Spooler service is not disabled.
- Install or reinstall the Microsoft Printer (Print to PDF).