Univer 2026 Import and Export: unitId or Snapshot?

September 29, 2026 · AI Development · ~ 12 min read

If your SaaS needs server-persisted documents for collaborative editing, use the unitId route; if you only need local or offline processing, use Snapshot. This guide compares the workflows, explains conversion-backend dependencies, and gives you a file round-trip checklist for spreadsheets that matter to your users.

An XLSX file imports, but the team is unsure whether to store a collaborative document or just transform the workbook.

Decision: choose unitId for server-persisted documents that enter collaborative editing; choose Snapshot for local or offline processing. Both routes still require the appropriate file-conversion backend and an export round-trip test.

This guide is for frontend and full-stack engineers adding Univer Sheets to a SaaS workflow, and product teams deciding how documents move through their service.
It is especially useful when the goal is offline processing or format conversion rather than shared editing.

Separate document persistence from file conversion

The choice is not simply “collaboration on” versus “collaboration off.” It involves two related but distinct questions:

Where does the document live after import?
Which service converts between workbook data and a file such as XLSX?

The official import and export guide describes a unitId route for documents used in collaborative workflows and a Snapshot route for workflows that do not need collaborative documents. It also documents the conversion-backend requirement. That dependency remains relevant whether the application later opens a shared document or processes workbook data offline.

This distinction prevents a common architecture mistake: treating Snapshot as a complete file-conversion service, or treating a returned unitId as proof that persistence and export are already configured. A working import response does not, by itself, establish that the document can be retrieved by the right users, saved by the server, or exported in the format your product promises.

The Univer server documentation is the companion reference for the server-side part of the design. Check it against the SDK and server versions in your project; do not infer that an example from a different version or deployment setup automatically matches your production environment.

Use unitId for a persistent collaborative document

Choose the unitId path when an imported file should become a server-managed document that users can reopen and edit together. In this workflow, the import process creates or identifies the document, and the resulting identifier is then used to load it in the collaborative environment. The official collaboration modules guide explains the collaboration components; the relevant question for your integration is whether the imported document reaches those components with the persistence and access behavior your application needs.

Treat the identifier as a reference to a document, not as a persistence configuration. The application still needs to establish how the server stores document state, how the intended user can access it, and how later changes become available to subsequent sessions. The quickstart’s data-saving guidance is useful when mapping the save flow, but the production acceptance test should follow your own authentication and document lifecycle.

Before selecting this route, trace the full lifecycle in your design:

The user uploads a file and the import path returns the document reference expected by the integration.
Your application associates that reference with the correct tenant, user, or workspace.
A permitted user can open the document in the collaborative environment.
A change made during editing is persisted and is present when the document is reopened.
The export path reads the intended saved state, not an earlier or unsaved version.

These are separate checks. For example, a document might load successfully for its creator but fail for another authorized user because access mapping was not completed. An export test might also pass immediately after import while missing a later edit if the save lifecycle is not connected as expected.

The cost of the unitId route is not a claim about a particular server bill; it is the engineering and operating scope you must account for. Your team needs a persistent document service, access rules, lifecycle handling, and a conversion backend for file operations. If the product does not need shared documents, those dependencies may add components that the workflow does not use.

Use Snapshot for offline processing and conversion

Choose Snapshot when the application needs workbook data for local or offline processing and does not need to create a collaborative document. In the documented flow, Snapshot import provides workbook data for the application to work with, and export uses that snapshot data to produce a file. The official import and export documentation is the reference for how those flows are described.

The distinction matters for lightweight utilities, batch-style processing, and workflows where the application transforms a workbook and returns a result without keeping a shared document available for later editing. It can simplify the persistence model because the workflow does not require a collaborative document lifecycle. It does not mean that the file conversion step can be skipped: the conversion backend remains a requirement to confirm for the deployed setup.

A Snapshot workflow should be designed around the data’s lifetime. Decide where imported workbook data is held while the operation runs, how the application handles failures before export, and whether the result needs to be retained after delivery. Those choices are application responsibilities; they should not be confused with the fact that the input was imported as a Snapshot.

Also avoid assuming that an offline path automatically has fewer compatibility risks. A Snapshot may be convenient for your application logic, but the exported file still needs to satisfy the same user-facing requirements as a collaborative export: expected sheets, formulas, formatting, images, and compatibility with the target software. These outcomes must be tested with files representative of your users’ work.

The Sheets API reference helps clarify the workbook and worksheet model used by the application. Use that model to define what your workflow expects to preserve; do not reduce acceptance to “the import call returned data.”

Check file-format boundaries before promising fidelity

A spreadsheet file format is not just a container label. CSV and TSV are text-oriented interchange formats, so they should not be presented as complete workbook round trips equivalent to formats that can carry richer spreadsheet structure. In particular, confirm how the chosen API handles multiple sheets, cell formatting, formulas, and images rather than assuming those workbook features survive a text-format export.

The official format guidance is the source to consult for the input and output formats supported by the current implementation. Support can depend on the API path and the versions you deploy. Check both directions independently: a format accepted for import does not necessarily establish that the same path supports the export behavior your product needs.

Workflow requirement	Route to evaluate	Main dependency to confirm	Acceptance focus
Shared document users can reopen and edit	`unitId`	Server persistence, collaboration setup, access control, and conversion backend	Reopen, edit, save, authorize another user, then export
Offline workbook processing	Snapshot	Snapshot import/export behavior and conversion backend	Data available to the processing step and expected file produced
Simple tabular exchange	The API path documented for CSV or TSV	Exact supported input and output formats	Rows, delimiters, encoding, and behavior when workbook features are absent

For CSV or TSV, define the product promise narrowly. If users expect one file to represent a workbook with multiple tabs, formulas, and presentation details, a text-based exchange may not meet that expectation. If the purpose is only to exchange tabular values, it may be suitable—but validate the exact output shape and document what is not retained.

A useful implementation rule is to make format choice explicit in the product flow. A user selecting a text format should not be led to believe that images, workbook-level structure, and visual formatting will necessarily be carried across. Likewise, an XLSX option should not be described as preserving every formula or visual detail until your target-environment tests establish that behavior.

Run an end-to-end workflow before release

Use a representative workbook from the target user group, not only a small hand-built file. Include multiple worksheets, formulas, formatting, and images if those features occur in real customer documents. Record observations separately: whether sheets remain present, whether formulas remain formulas, whether calculated results match expectations, whether appearance changes, and whether the exported file opens in the software your users rely on.

Formula behavior deserves its own acceptance record. Univer’s formula documentation describes formula functionality, but formula support in an SDK does not prove that every formula in a particular imported workbook will calculate or export as your users expect. Capture both the formula expression and its displayed result. If a result changes, investigate whether the cause is import, calculation, save, or export rather than marking the entire round trip simply “passed.”

For teams using the server-side conversion architecture, the server collaboration extensions documentation is relevant to understanding how server extensions fit the flow. Use the version and configuration actually deployed when validating; documentation should guide the test plan, not replace it.

Follow these implementation steps:

Identify the required user outcome: a persistent shared document, offline workbook data, or a tabular text exchange.
Choose unitId only when the document must enter a server-persisted collaborative lifecycle; otherwise evaluate Snapshot for the processing flow.
Confirm the documented input and output formats for the exact APIs and versions used by the project.
Configure the appropriate conversion backend and trace the request from upload through import to the resulting document reference or workbook data.
For the unitId route, test access, collaborative loading, saving, reopening, and exporting after an edit.
For the Snapshot route, test import, processing, export, and failure handling without creating a collaborative document.
Run the representative workbook through the complete flow and record structural, formula, visual, and application-compatibility results separately.
Repeat the acceptance run after changing the SDK, server, conversion configuration, or supported-format assumptions.

Use this acceptance checklist

The checklist is the release gate, not a substitute for deciding which route fits the workflow.

[ ] The product requirement states whether the document must be persistent and collaborative.
[ ] The chosen route matches that requirement: unitId for a server-managed collaborative document, or Snapshot for non-collaborative workbook processing.
[ ] The conversion backend is configured for the actual import and export path.
[ ] The deployed SDK and server versions have been checked against the current official format and server documentation.
[ ] The test workbook represents the files users are likely to upload, including multiple sheets and any formulas or images they depend on.
[ ] The import test records sheet structure, formula expressions, calculated results, formatting changes, and image behavior as distinct outcomes.
[ ] The export test confirms that the generated file opens in the target application and matches the product’s stated expectations.
[ ] CSV or TSV is offered only for workflows whose requirements match the tested text-format behavior.
[ ] The team has recorded which behaviors are verified in its own environment and which remain unsupported or untested.

Acceptance area	What to record	Why a single pass/fail is insufficient
Workbook structure	Sheet names, order, and presence after import and export	A file may retain basic data while changing workbook organization
Formulas	Formula text and displayed result before and after processing	Formula preservation and formula calculation are different outcomes
Visual content	Formatting and image behavior in the target application	Visual changes can matter even when cell values remain present
File compatibility	Whether the exported file opens and behaves as expected in the target software	Successful file generation alone does not establish user compatibility

Use the project’s real sample files for these checks. Do not publish a broad compatibility claim based on one workbook or infer universal formula, image, or formatting support from a successful test. A release note can state what was verified, the tested workflow, and any known exclusions without promising results for untested files.

Decision condition	Recommended direction	What to verify before implementation
Users need to reopen and collaboratively edit the imported document	`unitId`	Persistence, authorization, collaboration loading, saving, and later export
The application processes workbook data and returns a file without shared editing	Snapshot	Snapshot data flow and the conversion backend for the required output
The workflow exchanges plain tabular content only	CSV or TSV path supported by the selected API	Exact format support and the fields or workbook features outside the requirement
The file contains business-critical formulas, images, or complex formatting	Decide by persistence need, then run a representative round trip	Real target files, results in the deployed environment, and user-facing compatibility

FAQ

XLSX import route

For an XLSX workflow, choose unitId when the imported document must be stored by the server and enter collaborative editing. Choose Snapshot when the application needs workbook data for local or offline processing without creating a collaborative document. Confirm the required conversion backend and validate export separately; choosing an import route does not establish that the complete file workflow is configured.

Snapshot and collaboration

Snapshot can serve a workflow that does not need collaborative editing. It provides workbook data for the application’s processing path rather than requiring the product to treat every input as a shared document. File conversion remains a separate dependency, so verify the backend and test the output in the environment where the application will run.

XLSX export backend

A workbook object is not the same thing as a generated XLSX file. The export path must convert workbook data into the requested file format, so check the current Univer server and import/export documentation for the backend requirements that apply to your setup. Then test the result with a representative workbook; do not assume that a successful import alone proves export is ready.

Multiple sheets and formulas

Test sheet structure, formulas, displayed results, formatting, and images as separate acceptance items. A workbook can retain its sheets while a formula result or visual detail changes. Run the import, save or process, and export flow with files drawn from the intended user group, then confirm the output in the target application before making compatibility claims.

If the workflow is set, the remaining development friction is often the test environment: a local machine may be tied up, difficult for teammates to share consistently, or unavailable when the team needs to verify browser behavior on macOS. A rented Mac can provide a dedicated temporary environment for that client-side and browser validation, but it does not replace Univer’s conversion backend, and it is not the right substitute for a long-running production service or workloads that require physical interfaces. Teams evaluating that option can review nuvcloud’s service overview and, when a temporary US West environment fits their needs, the available access option.