Document conversion for Confluence Data Center

Still need help?

The Atlassian Community is here for you.

Ask the community

When you insert a file into a page (for example a Word document, or Excel spreadsheet), Confluence will generate thumbnail images of the file contents, so it can be viewed inline in the page, or in the preview. 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.  

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 only available for Confluence Data Center.

In Confluence Server, thumbnail generation is handled by Confluence, so the information on this page does not apply. 

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 three 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 process (sandbox) 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 document conversion process to complete, before terminating the process, and marking thumbnail generation for that file as failed. 

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. 

Last modified on Aug 31, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.