Office SDK
See the workflow
All storiesIntegration
IntegrationArchitecture4 min read

Preview and conversion consistency: source versions and layout inputs

Keep preview and converted output aligned through common models, explicit layout inputs, cache versioning, and approval guards.

Office SDK EditorialOffice SDK Editorial
107
Preview and conversion consistency: source versions and layout inputs: Shared document model, Layout inputs, Engine version, Surface contract.
Integration / Office SDK

Preview and conversion agree only when they process the same source state with compatible interpretation and layout inputs. A shared engine can help, but versioning, fonts, configuration, and cache behavior still matter. Bind approvals to the reviewed content so a preview cannot authorize a different converted file.

Identify the shared semantic model

Map how source bytes become paragraphs, tables, drawings, workbook cells, or slides in the engine's internal representation. The preview path and conversion path should agree on supported content and interpretation, even if their output formats differ. Record how unsupported features are represented or reported. A shared codebase does not prove identical behavior if one path applies different flags or preprocessing. Define source identity, engine version, and configuration as part of each request. This gives operators a way to explain why two outputs differ and to reproduce the same processing conditions during investigation.

Normalize layout inputs

Fonts, locale, page size, print settings, theme defaults, and external assets can affect rendering. Make those inputs explicit and consistent where parity is required. A server conversion using substitute fonts may paginate differently from a preview rendered with another font collection. For spreadsheets, define whether preview shows the sheet grid or the configured printed pages; those are different contracts. For presentations, specify treatment of notes and animations. Do not label every visible difference a defect before confirming that the surfaces were asked to produce the same representation of the same document state.

Four input groups determine output and cache identity.
Figure 1. Differences are explainable only when these inputs are recorded.

Follow an invoice approval

Suppose an accounts payable system previews an invoice before a reviewer approves the PDF archive copy. Bind both operations to the same source version and relevant layout configuration. Generate the preview and converted output, then compare key fields, line items, totals, and page coverage. If the source changes between viewing and conversion, require a new review or an explicit guarded decision. The reviewer must not approve one invoice while the archive stores another. This example shows that engine consistency and application version control are both necessary to make the approval meaningful.

Test parity and cache behavior

Maintain a representative corpus covering dense tables, special fonts, charts, multilingual text, and unusual page settings. Compare semantic content and visual output after engine or configuration changes. Cache keys should include source version and the processing inputs that affect output, rather than only a filename or business identifier. Invalidate or version caches deliberately when the engine changes. Record which output was generated by which engine release. Test partial failures and avoid serving an old preview beside a newly converted file without a clear label. Monitoring should distinguish parsing failures from rendering and delivery failures.

Cache identity includes processing inputs

source_version: identified immutable input
engine_release: parser and layout version
layout_profile: fonts, locale, page or print settings
surface: preview representation or converted format

These are illustrative cache dimensions, not a prescribed API. Include the inputs that actually affect your implementation. A cache indexed only by business document ID can serve an old preview after the source changes. A cache that ignores a font or engine update can preserve obsolete layout.

During an engine rollout, decide whether older cached output remains acceptable, is clearly labeled, or must be regenerated. Record the release that produced the output so investigation can reproduce it. Avoid requiring users to infer a processing version from a timestamp.

Define what parity means for each format

FormatParity question
Text documentContent, tables, page coverage, and required layout agree
SpreadsheetValues agree; grid view and print view differences are intentional
PresentationSlide content and geometry agree within the surface contract

For the invoice, prioritize line items, totals, identity, and page coverage. A harmless antialiasing difference is not the same as an omitted row. Define tolerances and critical checks from the business purpose, then preserve the compared outputs with their source and processing identities.

A version-bound review guards the conversion used for archiving.
Figure 2. Shared rendering cannot replace application-level version control.

PDecision notes-conversion contract

  • Use the same source version and documented processing configuration.
  • Define semantic support and intentional differences between surfaces.
  • Normalize fonts, locale, layout, and external asset handling.
  • Test parity across a representative corpus and engine upgrades.
  • Version caches and bind approvals to the content actually reviewed.

Further reading

Back to all stories

Keep reading.

All stories