Server Settings - Document

Overview

The Document Settings page configures ColdFusion's document service for converting Microsoft Office files (Word, Excel, PowerPoint) and other document formats to PDF, images, and other output formats. This service is essential for applications that need to programmatically manipulate, convert, or extract content from office documents.

ColdFusion's document service uses Apache OpenOffice or LibreOffice in headless mode to perform conversions, providing robust support for a wide range of document formats and conversion options.

Document Service Configuration

Configure the OpenOffice/LibreOffice service for document conversion operations.

Supported Office Versions

ColdFusion document service supports these office suites:

• Apache OpenOffice: Version 4.0 and later
• LibreOffice: Version 4.0 and later (recommended)
• Microsoft Office: Not directly supported (use OpenOffice/LibreOffice)

Installation Requirements

To use the document service:

• Install OpenOffice or LibreOffice on the ColdFusion server
• Ensure office suite is in system PATH or specify installation path
• Configure firewall to allow localhost communication on service port
• Verify ColdFusion process has permissions to execute office binaries
• Test document conversion after configuration

Supported Document Formats

Input Formats

Documents that can be converted:

• Microsoft Word: .doc, .docx, .rtf, .txt
• Microsoft Excel: .xls, .xlsx, .csv
• Microsoft PowerPoint: .ppt, .pptx
• OpenDocument: .odt, .ods, .odp, .odg
• Other Formats: .html, .xml, .wpd

Output Formats

Available conversion targets:

• PDF: Portable Document Format
• Images: PNG, JPEG, GIF, TIFF
• HTML: Web-ready HTML output
• Text: Plain text extraction
• Office Formats: Convert between office formats

Format Conversion Matrix

All major document formats support conversion to PDF, images, HTML, and text:

Using Document Service in CFML

Converting to PDF

Convert office documents 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 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:

// Read text content from document
docText = fileRead("c:\documents\report.docx");

// Or use cfpdf to extract text from PDF
cfpdf(
  action="extracttext",
  source="report.pdf",
  name="pdfText"
);
writeDump(pdfText);

<!--- Read text content from document --->
<cfset docText = fileRead("c:\documents\report.docx")>

<!--- Or use cfpdf to extract text from PDF --->
<cfpdf action="extracttext"
       source="report.pdf"
       name="pdfText">
<cfdump var="#pdfText#">

Batch Document Processing

Process multiple documents:

// 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

Conversion Timeout

Configure appropriate timeout values based on document complexity:

Memory Allocation

• OpenOffice/LibreOffice runs in 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

• Document service handles one conversion at a time by default
• Queue additional requests until current conversion completes
• Consider multiple document service instances for high volume
• Use different ports for multiple service instances
• Load balance across multiple conversion servers

Best Practices

Production Configuration

• Use LibreOffice instead of OpenOffice (more actively maintained)
• Keep office suite updated to latest stable version
• Configure adequate timeout for largest expected documents
• 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/LibreOffice is installed correctly
• Check installation path is configured correctly
• Ensure service port is not already in use
• Verify ColdFusion has permissions to execute office binaries
• Check firewall allows localhost communication on service port
• Review coldfusion-out.log for startup errors

Conversion Timeouts

If conversions consistently timeout:

• Increase timeout value for complex documents
• 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 to latest version of LibreOffice
• 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 LibreOffice 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 in LibreOffice
• Check file format is supported

Advanced Configuration

Multiple Service Instances

Configure multiple document services for high-volume processing:

• Run multiple LibreOffice instances on different ports
• Configure load balancing between instances
• Use separate servers for document processing
• Implement queue-based conversion architecture
• Monitor instance health and failover

Custom Conversion Profiles

• Create conversion profiles for different document types
• Configure PDF quality settings (compression, resolution)
• Customize image output resolution and format
• Define default fonts and fallback options
• Set page size and orientation defaults

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