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/oosdkclasses 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
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:
// 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:
// 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
cfdocumentattributes such asorientation,pageTypeandpdfa - 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