Skip to content
DocsentryDocsentry

Previews

Previews let people confirm they have the right document without downloading it - which matters both for speed and because Preview is a lower permission than Download. Someone can be given enough access to identify a document without being given its contents.

What gets previewed

Section titled “What gets previewed”
Kind How it is rendered Requires
Images (JPEG, PNG, GIF, WebP, TIFF, BMP) Rendered directly. Nothing extra.
PDF First page rasterised. Nothing extra.
Office formats (Word, Excel, PowerPoint, and their open equivalents) Converted to PDF, then rasterised. LibreOffice.
Anything else Not previewed. -

Which content types fall into each group is configurable through PreviewOptions:ImageContentTypes, PdfContentType, and OfficeContentTypes.

A PDF opened in the preview view, showing the rendered first page

The preview view renders the first page. Opening it needs Preview, not Download.

Previews and thumbnails

Section titled “Previews and thumbnails”

Two artefacts are produced per version:

  • a preview, bounded by PreviewOptions:MaxWidth and MaxHeight (1600x2000 by default)
  • a thumbnail, bounded by ThumbnailMaxEdge (320 pixels by default)

Both are stored as WebP by default (ArtifactFormat). Thumbnails are what you see on document cards in the explorer; the preview is what opens in the preview view.

Artefacts are per version, not per document. Checking in a new version produces new artefacts; the old version keeps its own.

When previews appear

Section titled “When previews appear”

Preview generation runs on a background job, not during the upload request. A document therefore appears in the folder immediately and gains its thumbnail shortly afterwards.

The job retries a failed render up to MaxAttempts times before giving up on that version, so a transient failure - a converter that was briefly busy - resolves itself without intervention.

Watermarks

Section titled “Watermarks”

Where governance settings require it, a watermark is composited onto the preview. This applies to the rendered preview, not to the stored original - downloading the document yields the file as uploaded.

Watermark rules are configured under governance. See Governance and retention.

Caching

Section titled “Caching”

Previews and thumbnails are immutable for a given version, so they are served with cache headers that let the browser reuse them. Thumbnails in particular are cached, which is what keeps a folder of many documents from re-fetching every image on each visit.

The preview view itself is served without caching, because what it displays depends on the caller’s permissions.

Office conversion

Section titled “Office conversion”

Office previews go through soffice. Two settings matter:

Setting Purpose
PreviewOptions:SofficePath Absolute path to the executable. Leave empty to auto-discover it on the current platform.
PreviewOptions:SofficeTimeout Bound on a single conversion, one minute by default.

The timeout exists because a malformed document can make the converter hang. When it trips, that version’s preview fails and is retried; it does not block other work.

If Office previews stopped working after a host change, the executable path is the first thing to check.

Permissions

Section titled “Permissions”

Viewing a preview requires Preview on the document. Downloading the original requires Download. The split is intentional and is a genuinely useful grant to hand out - see Permission model.

Content that has not cleared antivirus scanning is not served in any form, preview included. See Antivirus.

Section titled “Related”