Server Settings - Document

Configure document handling and Office file conversion settings

Overview

The Document Settings page configures the OpenOffice installation ColdFusion uses for converting Microsoft Office files, such as Word documents and PowerPoint presentations to PDF. You point ColdFusion at a local OpenOffice installation or at a remote OpenOffice host and port. This service is essential for applications that need to programmatically manipulate, convert, or extract content from office documents.

Adobe's documentation covers Apache OpenOffice. For a remote host, OpenOffice runs headless with a socket listener that ColdFusion connects to. Source: Adobe: Install integrated technologies (Configuring OpenOffice)

Document Service Configuration

Configure the OpenOffice installation used for document conversion operations.

Office Installation Path

Set
At install (non-Windows) or on this page
Purpose
Path to a local OpenOffice installation

On non-Windows platforms the installer prompts for the OpenOffice directory. Restart ColdFusion after changing it here.

Remote Host and Port

Example port
8900 (from Adobe's example)
Purpose
Host and port of a remote OpenOffice listener

Start OpenOffice on the remote machine with soffice -nologo -nodefault -norestore -nofirststartwizard -headless -accept "socket,host=<ip>,port=8900;urp;StarOffice.ServiceManager", then enter that host and port. Make sure the port is reachable from ColdFusion.

Supported Office Suites

Adobe's OpenOffice instructions refer to Apache OpenOffice (its example paths use openoffice.org3). Microsoft Office is not used for these conversions. If you use another suite or version, test it before relying on it.

Installation Requirements

To use the document service:

  • Install OpenOffice on the ColdFusion server, or run it headless on a remote host
  • Specify the OpenOffice directory (or remote host and port) in Server Settings > Document, then restart ColdFusion
  • For JEE deployments, add the lib/oosdk classes and JAR files to the class path as described in Adobe's OpenOffice instructions
  • Verify ColdFusion process has permissions to execute office binaries
  • Test document conversion after configuration

Supported Document Formats

Adobe documents converting Word documents and PowerPoint presentations to PDF with cfdocument srcfile once OpenOffice is configured. PowerPoint to HTML uses cfpresentation format="html".

Word (.doc, .docx)

To PDF
Yes, with cfdocument srcfile (OpenOffice)

PowerPoint (.ppt, .pptx)

To PDF
Yes, with cfdocument srcfile
To HTML
Yes, with cfpresentation format="html"

Excel (.xls, .xlsx)

Handled by
cfspreadsheet, not the document service
Conversions
Read to a spreadsheet object, query, CSV or HTML string; write from a query, spreadsheet object or CSV

Using Document Service in CFML

Converting to PDF

Convert office documents to PDF:

Convert Word Document to PDF
// Convert Word document to PDF
cfdocument(
  format="pdf",
  srcfile="c:\documents\report.docx",
  filename="output.pdf",
  overwrite="yes"
);
<cfdocument format="pdf"
            srcfile="c:\documents\report.docx"
            filename="output.pdf"
            overwrite="yes">
</cfdocument>

Converting to Images

Convert document pages to images:

Generate PDF Thumbnails
// Generate thumbnails from PDF
cfpdf(
  action="thumbnail",
  source="report.pdf",
  destination="c:\thumbnails",
  format="png",
  scale="25",
  overwrite="yes"
);
<cfpdf action="thumbnail"
       source="report.pdf"
       destination="c:\thumbnails"
       format="png"
       scale="25"
       overwrite="yes">

Extracting Text Content

Extract text from documents:

Extract Text from Document
// A .docx file is a ZIP archive, so fileRead() returns raw bytes, not text.
// Convert the document to PDF first, then extract the text.
cfdocument(
  format="pdf",
  srcfile="c:\documents\report.docx",
  filename="report.pdf",
  overwrite="yes"
);

cfpdf(
  action="extracttext",
  source="report.pdf",
  name="pdfText"
);
writeDump(pdfText);
<!--- A .docx file is a ZIP archive, so fileRead() returns raw bytes, not text.
      Convert the document to PDF first, then extract the text. --->
<cfdocument format="pdf"
            srcfile="c:\documents\report.docx"
            filename="report.pdf"
            overwrite="yes">
</cfdocument>

<cfpdf action="extracttext"
       source="report.pdf"
       name="pdfText">
<cfdump var="#pdfText#">

Batch Document Processing

Process multiple documents:

Batch Convert Word Documents to PDF
// Get all Word documents in directory
docFiles = directoryList("c:\documents", false, "name", "*.docx");

// Convert each document to PDF
for (docFile in docFiles) {
  cfdocument(
    format="pdf",
    srcfile=docFile,
    filename=replaceNoCase(docFile, '.docx', '.pdf'),
    overwrite="yes"
  );
}
<!--- Get all Word documents in directory --->
<cfset docFiles = directoryList("c:\documents", false, "name", "*.docx")>

<!--- Convert each document to PDF --->
<cfloop array="#docFiles#" index="docFile">
  <cfdocument format="pdf"
              srcfile="#docFile#"
              filename="#replaceNoCase(docFile, '.docx', '.pdf')#"
              overwrite="yes">
  </cfdocument>
</cfloop>

Performance Settings

Memory Allocation

  • OpenOffice runs in a separate process
  • Configure office suite memory in its own settings
  • Monitor memory usage during conversions
  • Restart service periodically for memory cleanup
  • Consider dedicated server for heavy document processing

Concurrent Conversions

  • Load test concurrent conversions before production
  • Consider a separate OpenOffice host for high volume

Best Practices

Production Configuration

  • Keep office suite updated to latest stable version
  • Monitor document service process health
  • Implement retry logic for failed conversions
  • Log conversion operations for troubleshooting

Document Quality

  • Test conversions with representative sample documents
  • Verify formatting preservation in output
  • Check font embedding in PDF outputs
  • Validate image quality and resolution
  • Test with documents containing complex elements (tables, charts, images)

Security

  • Validate uploaded documents before conversion
  • Scan documents for malware before processing
  • Limit document size to prevent resource exhaustion
  • Restrict file types to business requirements
  • Use isolated directories for conversion operations
  • Clean up temporary files after conversion

Error Handling

  • Implement try/catch blocks around conversion operations
  • Handle timeout exceptions gracefully
  • Provide user-friendly error messages
  • Log detailed error information for debugging
  • Implement fallback conversion strategies
  • Notify administrators of repeated failures

Troubleshooting

Document Service Won't Start

If the document service fails to start:

  • Verify OpenOffice is installed correctly
  • Check installation path is configured correctly
  • For a remote OpenOffice host, confirm the listener is running on the configured port
  • Verify ColdFusion has permissions to execute office binaries
  • Check that a firewall is not blocking ColdFusion from reaching that port
  • Review coldfusion-out.log for startup errors

Conversion Timeouts

If conversions consistently timeout:

  • Check server has adequate CPU and memory resources
  • Verify documents aren't corrupted or password-protected
  • Test with simpler documents to isolate issue
  • Monitor system resources during conversion
  • Consider breaking large documents into smaller chunks

Poor Conversion Quality

If output quality is unsatisfactory:

  • Update the office suite
  • Check source document quality and formatting
  • Verify fonts are available on server
  • Adjust conversion settings (resolution, format options)
  • Test different office suite versions
  • Consider pre-processing documents to simplify formatting

Service Becomes Unresponsive

If document service stops responding:

  • Restart ColdFusion server to restart document service
  • Check for hung office processes and kill them
  • Review memory usage (may need more memory)
  • Implement scheduled service restarts during low-usage periods
  • Monitor for problematic documents causing hangs

Missing Fonts in Output

If converted documents show wrong fonts:

  • Install required fonts on ColdFusion server
  • Register fonts with ColdFusion font management
  • Configure the office suite to use specific fonts
  • Embed fonts in source documents when possible
  • Use font substitution mapping in office suite

Conversion Fails for Specific Documents

If certain documents won't convert:

  • Verify document isn't corrupted (open in office application)
  • Check for password protection or DRM restrictions
  • Test with simplified version of document
  • Review document for problematic elements (macros, external links)
  • Try opening and re-saving it in OpenOffice
  • Check file format is supported

Advanced Configuration

Multiple Service Instances

Configure multiple document services for high-volume processing:

  • Run OpenOffice on a separate host and enter its host and port on the Document page
  • Use separate servers for document processing
  • Implement queue-based conversion architecture
  • Monitor instance health and failover

Controlling Output

  • Control output per call with cfdocument attributes such as orientation, pageType and pdfa
  • Wrap common attribute sets in a shared function so conversions stay consistent

Integration with Other Services

  • Combine with PDF manipulation (cfpdf)
  • Use with image processing (cfimage)
  • Integrate with document storage services
  • Connect to workflow automation systems
  • Enable API access for remote conversions

Related Resources

Server Settings - Document | ColdFusion Administrator | CFGuide