Document conversion for Confluence Data Center

When you insert a file into a page (for example a Word document, or Excel spreadsheet), Confluence will convert the contents to a format that can be viewed inline in the page, in the preview, or in some macros. This can be quite memory and CPU intensive, and has been known to cause out of memory errors when processing very complex files. 

In Confluence Data Center we minimize the impact by handling the conversion in an external process pool, which is a seperate pool of processes, managed by Confluence. These processes (also known as sandboxes) can crash or be terminated, and will be restarted automatically by Confluence, without affecting the Confluence application itself.  

For example, If you insert a very complex file, and the process crashes or is terminated, thumbnail generation will fail. When this happens, a placeholder thumbnail will be used on the page, and a download option will be provided in the file preview. Confluence Data Center doesn't re-attempt to generate thumbnails for failed files.  A good example of a complex file, is a PowerPoint presentation that contains 50 embedded Excel charts. Most files will be processed without any problems. 

The external process pool is used for the following conversions:

• thumbnail generation for images and documents inserted into a page, or viewed in the preview.
• HTML conversion for Word and Office documents viewed using the Office Word and Office Excel macros. 

Configure the external process pool

In most cases the default values will be adequate, however system administrators can change the behaviour using system properties. For example you may want to increase the size of the pool (the number of processes available), or increase the time limit before a process is terminated. Here are the main properties you may need to change:

• conversion.sandbox.pool.size
  Use this property to increase the number of processes (sandboxes) in the pool. You'll need to allow additional memory on each node for each additional process. 
• conversion.sandbox.memory.limit.megabytes 
  Use this property to limit the amount of memory each thumbnail generation process in the pool can consume. 

• document.conversion.sandbox.memory.requirement.megabytes
  Use this property to limit the amount of memory each HTML conversion process in the pool can consume. 

• document.conversion.sandbox.request.time.limit.secs 
  Use this property to change the amount of time (in seconds) that the sandbox will wait for the conversion process to complete, before terminating the process.

See Recognized System Properties for a full description of these properties, plus a few additional properties that can be used to fine-tune, or disable the sandboxes completley. 

Re-attempt thumbnail generation for failed files

Confluence does not re-attempt to generate thumbnails for a failed attachment, and re-inserting the attached file into the editor will not trigger the process. 

If you do want to re-attempt thumbnail generation, for example after increasing the request time limit, you will need to re-upload the file, and then re-insert it into the page. 

Other system properties that affect document conversion

The system properties listed on this page apply specifically to the external process pool:

• confluence.document.conversion.imaging.enabled.tif
  Use this property to enable document conversion for TIFF files. This is disabled by default. 

• confluence.document.conversion.imaging.enabled.psd
  Use this property to enable document conversion for Photoshop PSD files. This is disabled by default. 

• confluence.document.conversion.imaging.convert.timeout
  Use this property to change the default 30 second time limit which applies when performing document conversion on complex image files (such as ICO, EMF, WMF).

• confluence.document.conversion.slides.convert.timeout
  Use this property to change the default 30 second time limit which applies when performing document conversion on presentation files (such as PPT, PPTX).

To override the default value of these properties, you'll need to use the conversion.sandbox.java.options system property to pass the property to the JVMs that make up the external process pool.

If you decide to increase the timeout for generating thumbnails in the external process pool using the document.conversion.sandbox.request.time.limit.secs system property, you may also want to change the timeout for complex image files or presentations using the system properties above. Alternatively, you could keep the default, and allow these types of files to fail sooner.