Word Converter

The native Word Converter is the standard converter for docx documents in webPDF 10. It is built into the server, processes docx files locally, and is designed to deliver office-level conversion quality without requiring Microsoft Word, Microsoft Office via Office Bridge, or an online service such as the SharePoint Bridge.

When webPDF uses the Word Converter

For the docx office format, webPDF uses the following decision order during a conversion:

1. Office Bridge, if the officeBridge parameter node is present in the web service call
2. SharePoint Bridge, if the sharePointBridge parameter node is present in the web service call
3. Native Word Converter for docx
4. Outside In Technology for the remaining fallback case

This means that docx is converted with the native Word Converter by default in webPDF 10 unless you explicitly request an alternative converter in the /converter call.

note

The native Word Converter is specific to docx and is the complete native alternative for this format in webPDF 10.

caution

For other Office formats such as doc, xls, ppt, xlsx or pptx, the native Word Converter is not used. These formats still require their existing conversion path, such as Office Bridge, SharePoint Bridge, or Outside In Technology.

Why use the Word Converter

For docx, the native Word Converter is usually the preferred option because it combines high conversion quality with simple server operation:

• Office-level quality for modern Word documents
• Platform-independent operation without Windows-only automation
• No local (server) Microsoft Office installation required
• No external cloud service required
• Local processing inside webPDF
• No licensing issues when installing Office on a server
• No unstable OLE/COM dependencies
• Enabled by default for docx in webPDF 10

In practice, this makes the native converter easier to operate than bridge-based alternatives and better suited for Linux and container-based deployments.

Why it is better than the alternatives for docx

Converter	Strengths	Limitations compared with Word Converter
Word Converter	Native docx standard in webPDF 10, office-level quality, platform-independent, local processing	Supports docx only
Office Bridge	Uses locally installed Microsoft Office	Requires Windows, requires Microsoft Office, depends on desktop automation, must be selected explicitly
SharePoint Bridge	Uses Microsoft 365 and SharePoint Online for Office document conversion	Requires cloud connectivity, external Microsoft service dependencies, and explicit selection in the web service call
Outside In Technology	Broad format coverage across many file types and platform-independent operation	General-purpose fallback, not the default for docx in webPDF 10

For docx, the native Word Converter is generally the better operational choice because it keeps the conversion inside webPDF while avoiding the operating system, licensing, automation, and availability constraints of Microsoft Office integration.

Compared with the SharePoint Bridge, it also avoids sending documents to an external online service for conversion.

Compared with Outside In, it is the dedicated docx converter in webPDF 10 and the default path for modern Word documents.

Choosing an alternative converter

If you want to override the default behavior for a single conversion, add the corresponding parameter node to the /converter call.

Use the Office Bridge:

{
  "converter": {
    "officeBridge": {}
  }
}

Use the SharePoint Bridge:

{
  "converter": {
    "sharePointBridge": {}
  }
}

Without these parameters, webPDF uses the standard converter for the detected format. For docx, this is the native Word Converter in webPDF 10.

If the officeBridge node is present, webPDF uses the Office Bridge. If the sharePointBridge node is present, webPDF uses the SharePoint Bridge.

Switching off the integrated converter

The enabled attribute of the converter.office.word parameter node decides whether the integrated Word Converter is used at all. It defaults to true. With "enabled": false, the integrated converter is skipped and the docx document is converted by Outside In Technology instead. To return to the integrated converter, omit the attribute or set it to true.

{
  "converter": {
    "office": {
      "word": {
        "enabled": false
      }
    }
  }
}

For a Word document, webPDF decides in this order:

1. A requested Office Bridge, if Word is enabled for it in the server configuration. If the Office Bridge is not available, the conversion ends with an error.
2. A requested SharePoint Bridge. If it is not available, the conversion ends with an error.
3. The integrated Word Converter, for docx documents only and only if it is switched on.
4. Outside In.

If the converter chosen this way fails, the conversion ends with its error; webPDF does not try the next one.

note

A requested Office Bridge or SharePoint Bridge has priority and is not affected by enabled. The attribute only decides between the integrated converter and Outside In.

Locale and time zone

The locale and timeZone attributes of the converter parameter node are evaluated by the Word Converter. The locale applies to text that has no language of its own and to the document language of the PDF if the document states none; a language stated in the document takes precedence. The timeZone sets the time zone in which the DATE and TIME fields read the current date and time. Without the attributes, the default of the Converter web service applies, then the default of the server, otherwise the locale and time zone of the Java runtime of the server. Form, precedence and errors are described under locale and time zone.

Font resolution

The converter asks for the font that the document names for a piece of text, in the style the document requests (regular, bold, italic, bold italic). If that font is installed on the server, it is used and nothing is reported. If it is not installed, the converter goes through the following stages and uses the first one that delivers a font. The stages 1 and 2 belong to the substitute fonts; enabled="false" switches them off (see "Without substitute fonts" below).

Stage	Font that is used	Where the font is found, chosen or configured	Report (report parameter of the call)
0	The font named in the document, if it is installed	Directories, Custom font directory, Fonts installed with webPDF	None
1	The first installed alternate name of the document: the names listed with w:altName for this font in the font table of the document	The font directories of the web service, as for stage 0; see How the substitution works and Fonts under Linux	FONT_REPLACED, alias usage (fontAliasUsage, -107)
2	The font of the same metrics: Arial by Liberation Sans, Calibri by Carlito and so on, or a pair of your own	Built-in pairs, Configuration, Substitute fonts on Linux	FONT_REPLACED, alias usage (-107)
3	The font that fits the character set of the text, usually the default font; a symbol font such as Symbol or Wingdings is handled here as well	Default font, Symbol character sets	Alias usage (-107) if a font declares the character set; FONT_MISSING, missing (fontIsMissing, -108) if none does and the default font is used instead
4	The replacement chain for characters that the font so far does not draw, and the last resort Helvetica	Default font, Font decisions	Alias usage (-107) if the font draws the characters; FONT_MISSING (-108) if characters cannot be drawn or Helvetica is used

Both options of the report parameter are off by default. With fontAliasUsage, the replacement of stages 1 to 3 gives the result -107 and the message names both fonts; with fontIsMissing, a FONT_MISSING entry gives -108. Without the options the decision is written to the server log only. See reports of the native converters and error codes.

Example

A document sets its text in Calibri. Its font table names the alternate fonts Liberation Serif and Roboto for it, and Calibri is not installed on the server.

• If Liberation Serif is installed, stage 1 applies: the text is set in Liberation Serif, in the requested style. The report states that the font Calibri (regular) was replaced by Liberation Serif (regular), alias usage, -107. Carlito is not used, even if it is installed, as long as Liberation Serif draws all characters of the text.
• If Liberation Serif is not installed but Roboto is, Roboto is used. If neither is installed, stage 2 applies: Carlito, reported in the same way.
• If none of these fonts is installed, stage 3 applies: usually the default font, reported as alias usage if it declares the character set of the text. Characters it does not draw lead to stage 4.

Alternate names of the document

• Only the first installed name counts. The names are tried in the order of the document, as ECMA-376 (Office Open XML, part 1, section 17.8.3.1) prescribes: an application that cannot find a font by its name tries each alternate name in turn and uses the first font it finds, before it substitutes by the metrics of the font. In the example, Roboto is not used when Liberation Serif is installed, even if Liberation Serif lacks a character of the text.
• Only installed fonts count. An alternate name that is not installed is skipped. The substitute font of an alternate name is not looked for: if the document names Calibri as the alternate name of a font that is not installed, and only Carlito is installed, the text is not set in Carlito for that reason; stage 2 then applies to the font the document asked for.
• The case of the name is ignored.
• Fonts embedded in the document are not used as a replacement for an alternate name.
• Only Word documents carry alternate names, in the font table of the document.

Choice by the characters of the text

When the text has characters, the stages 1 to 3 are checked in this order, and the first font that draws all characters of the text is used. The alternate name of the document is therefore the first candidate, the font of the same metrics the second and the font that fits the character set the third. If a font lacks a character, for example a hyphen (U+2010) in Carlito, the whole text moves on to the next candidate. If no font draws all characters, the one that draws most of them is used; with equal numbers, the earlier one. A candidate that is not readable, may not be embedded or cannot be loaded is passed over and named in the server log.

Text without characters and symbol fonts

An empty paragraph, a paragraph mark or a symbol font has no characters to check. For these requests the stages work as follows:

• The alternate name of the document is used first, without a check of the characters, so that an empty line gets the same font and the same line height as the text of the same format.
• It is only used if it fits the character set that the request names. A request for a symbol character set is not set in a text font that does not declare it; it stays with stage 2 and 3.
• A font that cannot be used is passed over, and the following stage applies.

Fall back

If no stage delivers a font that draws the text, the default font is used, followed by the other fonts of the replacement chain and, as the very last resort, the PDF standard font Helvetica, which is not embedded. The order of the default font itself is described under Default font; it is not repeated here. Characters that no installed font draws are drawn as the font's .notdef glyph - usually an empty box - where the font provides one, otherwise they are left out; the report names them in either case.

Without substitute fonts

With enabled="false" in the fontSubstitution element of application.xml, stages 1 and 2 are skipped and the text is not chosen by its characters. The server behaves as it did before substitute fonts existed: the installed font, otherwise the font that fits the character set or the default font, and Helvetica as the last resort. The alternate names of the document are not used either. With useDefaults="false", only the built-in pairs of stage 2 are switched off; the alternate names of the document stay in use. See Configuration for the settings.

Conversion behavior

The native Word Converter handles docx documents directly in webPDF and supports the regular converter workflow, including page selection, custom page settings, font embedding, and optional conversion reports for content and font issues.

Password-protected docx documents can also be processed when the correct document password is supplied in the converter call.

See font decisions in the native Word Converter for how a font that cannot be used is replaced and, optionally, reported.

Format scope

The native Word Converter replaces the alternative docx conversion paths in webPDF 10 and is the default choice for this format.

For other Office document formats such as xlsx, doc, xls, ppt, and pptx, webPDF still relies on Office Bridge, SharePoint Bridge, or Outside In Technology, depending on the selected and available conversion path.