All storiesIntegration

Document format routing: choose preview, editing, conversion, or download

Choose preview, editing, conversion, or download paths using validated content type and task requirements, with clear fallback behavior.

Document format routing: choose preview, editing, conversion, or download: Format detection, Capability check, Routing policy, Protected inputs.
Integration / Office SDK

Document format routing is the decision that maps a validated file and requested operation to preview, editing, conversion, download, or rejection. Recognizing an extension is not enough: a file may support preview but not editing, or be quarantined and unavailable for either. Keep the same routing policy behind menus, deep links, and jobs.

Detect content, then check the requested capability

File extensions, declared MIME types, and inspected structure provide evidence about content type, but they serve different purposes and can disagree. Validate uploads using maintained tooling and an appropriate allowlist before routing. Then consult the documented capabilities of the selected service for the intended operation. A format supported for preview may not support editing or round trip export. Record those distinctions in a capability matrix rather than treating a recognized extension as proof that every document workflow is available for that file.

Use a reviewed decision model across entry points

Define outcomes such as open in editor, generate preview, show an existing immutable rendition, download only, require a password workflow if supported, or reject with guidance. Include permissions and document state, such as quarantine or pending conversion, in the decision. Keep the policy centralized enough that list actions, direct links, and backend jobs agree. A browser menu that offers Edit while the server routes the same file to download creates a confusing contract and can expose paths that were never included in acceptance testing.

Input to the decisionExample distinction
Validated typeThe inspected container disagrees with its filename extension
Requested operationPreview support exists but round-trip editing is unverified
Lifecycle stateValidation pending versus released content
AuthorizationViewing allowed but downloading denied
Processor capabilityConfigured service supports the exact requested path

Keep a reason code with the routing result so support can explain why a file opened in a particular view. It need not expose implementation detail in the ordinary interface. A message such as “This format is available for download only” can be backed by a precise policy result without displaying internal service names.

When adding a format, test every enabled action rather than only the default icon click. Direct editor URLs, batch conversion, restore flows, and shared links can bypass a frontend menu. The server should reach the same supported decision for the same identity, operation, and state. An unsupported operation should fail predictably without entering a repeated conversion loop.

Validated format, permissions, state, and capability determine processing, waiting, or rejection.
Figure 1. A download fallback must preserve validation and authorization boundaries.

Ambiguous, encrypted, and damaged inputs differ

When filename and inspected content disagree, do not silently select the most permissive route. Apply the validation policy and give a useful explanation. Encrypted documents, damaged containers, and unsupported embedded features may need specific handling distinct from an unknown extension. Avoid repeated conversion attempts for a permanent input limitation. If a safe download fallback is allowed, keep it subject to normal authorization and content handling controls. A fallback should help the user complete an approved task, not bypass the validation boundary that blocked processing.

Maintain the supported-route matrix

  • Track preview, editing, import, and export support separately.
  • Validate actual content before selecting a processing path.
  • Apply the same policy to menus, deep links, and background jobs.
  • Provide specific recovery guidance for unsupported, encrypted, or damaged inputs.
  • Retest representative routes when upgrading processors or adding formats.

Exercise a mixed project folder

Create a test folder containing a workbook, a PDF, an image, a plain text file, an unsupported archive, and a deliberately mislabeled harmless file. Request preview and edit actions with users who have different permissions. Compare visible actions, backend routing decisions, and final outcomes. Add a pending conversion and a quarantined object to confirm that lifecycle state affects routing. This scenario verifies the complete policy instead of only checking that each extension has an icon or that a filename based switch statement returns a value.

Representative file types and lifecycle states test both visible actions and backend decisions.
Figure 2. Repeat direct-link and background-job routes, not only the file-list menu.

Choose the route from validated capability

Requested actionRequired evidenceFallback when unavailable
EditValidated content type, edit support, permission, and usable document stateOffer preview or download with a specific reason
PreviewValidated content type, render support, and read permissionUse an existing immutable rendition or an authorized download
DownloadAuthorized access to the original filePreserve the source without implying preview or edit support
Reject or quarantineValidation failure, unsafe input, or unavailable document stateExplain the blocked condition and the next supported action

Route a document through one reviewed decision sequence

Use 5 files, 4 requested operations, and 2 user roles to cover supported, mislabeled, pending, unsafe, and unsupported routes.

  1. Inspect the actual content type and current document state.
  2. Name the requested operation: preview, edit, convert, or download.
  3. Check operation support and the user permission required for that route.
  4. Select the supported processor, a specific fallback, or an explicit rejection.
  5. Apply the same rule to menus, deep links, and background jobs.

Further reading

Back to all stories

Keep reading.

All stories