Session and workbook

Opening a workbook subset, saving, the viewport, recovery, properties, comparing, and merging revisions. Terms are in the glossary.

Revision-merge limits

The merge_workbook_revisions operation checks the size of what it’s given, and refuses if the limit is exceeded — without changing anything.

Limit	Value	Refusal code
edits in a single merge	4 096	workbook-revision-merge-mutation-limit-exceeded
history entries in a merge	100	—
bytes of text in a cell	32 767	—
bytes in a formula	8 192	—
bytes in a sheet key	1 024	—
:::

Operations on this page — 19

• check_workbook_compatibility
• close_workbook_subset
• compare_workbook_versions
• diagnose_file_open_recovery
• document_properties_lifecycle
• inspect_workbook_privacy
• merge_workbook_revisions
• open_password_protected_workbook_subset
• open_password_protected_workbook_subset_from_bytes
• open_workbook_subset
• open_workbook_subset_from_bytes
• publish_file_open_recovery
• replay_workbook_history
• save_workbook_subset
• save_workbook_subset_to_bytes
• synchronize_workbook_viewport
• workbook_accessibility
• workbook_links_manager
• workbook_window_session_command

check_workbook_compatibility

Checks a workbook’s compatibility.

Request

Field	TypeScript type	Req.
operation	"check_workbook_compatibility"	yes
subsetId	string	yes
target	CompatibilityTarget	yes
readOnly	boolean	no
requestedBackend	ComputeBackendKind | null	no

Response on success · check_workbook_compatibility

Field	TypeScript type	Req.
operation	"check_workbook_compatibility"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
report	CompatibilityInventoryReport	yes

Minimal JSON template

{
  "operation": "check_workbook_compatibility",
  "subsetId": "<subsetId>",
  "target": "<CompatibilityTarget>",
  "requestedBackend": "native-desktop"
}

close_workbook_subset

Closes a workbook session and releases the records tied to it.

Success doesn’t mean the workbook closed

Check the closed field in the response, not just ok. For a workbook with approved macros, closing triggers the Workbook_BeforeClose handler, and it can cancel the close — just as in Excel. In that case you get ok: true and closed: false: the session stays alive, subsetId is still valid, the workbook is still open.

If the handler itself crashes, the response is the refusal workbook-before-close-handler-failed, and the workbook again stays open. A workbook with no macros, or a build with no automation provider, doesn’t have this path — closing is unconditional.

Request

Field	TypeScript type	Req.
operation	"close_workbook_subset"	yes
subsetId	string	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · close_workbook_subset

Field	TypeScript type	Req.
operation	"close_workbook_subset"	yes
subsetId	string	yes
closed	boolean	yes
releasedClipboardCount	number	yes
remainingSessionCount	number	yes

Minimal JSON template

{
  "operation": "close_workbook_subset",
  "subsetId": "<subsetId>",
  "requestedBackend": "native-desktop"
}

compare_workbook_versions

Compares workbook versions.

Request

Field	TypeScript type	Req.
operation	"compare_workbook_versions"	yes
currentSourceUri	string	yes
versionSourceUri	string	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · compare_workbook_versions

Field	TypeScript type	Req.
operation	"compare_workbook_versions"	yes
diff	WorkbookVersionStructuralDiff	yes

Minimal JSON template

{
  "operation": "compare_workbook_versions",
  "currentSourceUri": "<string>",
  "versionSourceUri": "<string>",
  "requestedBackend": "native-desktop"
}

diagnose_file_open_recovery

Diagnoses recovery on file open.

Request

Field	TypeScript type	Req.
operation	"diagnose_file_open_recovery"	yes
sourceUri	string	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · diagnose_file_open_recovery

Field	TypeScript type	Req.
operation	"diagnose_file_open_recovery"	yes
plan	ContractFileRecoveryPlan	yes

Minimal JSON template

{
  "operation": "diagnose_file_open_recovery",
  "sourceUri": "file:///path/book.xlsx",
  "requestedBackend": "native-desktop"
}

document_properties_lifecycle

Document properties — “File” → “Info” → “Properties”, including the advanced ones.

Request

Field	TypeScript type	Req.
operation	"document_properties_lifecycle"	yes
subsetId	string	yes
intent	ContractDocumentPropertiesIntent	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · document_properties_lifecycle

Field	TypeScript type	Req.
operation	"document_properties_lifecycle"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractDocumentPropertiesResult	yes

Minimal JSON template

{
  "operation": "document_properties_lifecycle",
  "subsetId": "<subsetId>",
  "intent": "<ContractDocumentPropertiesIntent>",
  "requestedBackend": "native-desktop"
}

inspect_workbook_privacy

Inspects a workbook’s privacy.

Request

Field	TypeScript type	Req.
operation	"inspect_workbook_privacy"	yes
subsetId	string	yes
intent	ContractPrivacyInspectorIntent	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · inspect_workbook_privacy

Field	TypeScript type	Req.
operation	"inspect_workbook_privacy"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractPrivacyInspectorResult	yes

Minimal JSON template

{
  "operation": "inspect_workbook_privacy",
  "subsetId": "<subsetId>",
  "intent": "<ContractPrivacyInspectorIntent>",
  "requestedBackend": "native-desktop"
}

merge_workbook_revisions

Merges workbook revisions.

Request

Field	TypeScript type	Req.
operation	"merge_workbook_revisions"	yes
subsetId	string	yes
workbookId	string	yes
baseRevision	number	yes
local	ContractWorkbookRevisionDelta	yes
incoming	ContractWorkbookRevisionDelta	yes
expectedRevision	number	yes
viewport	ViewportWindow | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · merge_workbook_revisions

Field	TypeScript type	Req.
operation	"merge_workbook_revisions"	yes
subsetId	string	yes
workbookId	string	yes
baseRevision	number	yes
localRevision	number	yes
incomingRevision	number	yes
outcome	ContractWorkbookRevisionMergeOutcome	yes
appliedMutationCount	number	yes
conflicts	ContractWorkbookRevisionConflict[]	yes
changedKeys	string[]	yes
dirty	boolean	yes
recalcNeeded	boolean	yes
workbookHistory	ContractWorkbookHistoryProjection	yes

Minimal JSON template

{
  "operation": "merge_workbook_revisions",
  "subsetId": "<subsetId>",
  "workbookId": "<string>",
  "baseRevision": 0,
  "local": "<ContractWorkbookRevisionDelta>",
  "incoming": "<ContractWorkbookRevisionDelta>",
  "expectedRevision": 0,
  "requestedBackend": "native-desktop"
}

open_password_protected_workbook_subset

Opens a password-protected workbook: the file path and password are in the request. After that, the session works just like an ordinary open.

Request

Field	TypeScript type	Req.
operation	“open_password_protected_workbook_subset”	yes
sourceUri	string	yes
viewport	ViewportWindow | null	no
delimitedOpenOptions	ContractDelimitedOpenOptions | null	no
password	string	yes

Minimal JSON template

{
  "operation": "open_password_protected_workbook_subset",
  "sourceUri": "<sourceUri>",
  "password": "<password>"
}

open_password_protected_workbook_subset_from_bytes

The same for a workbook passed as bytes: the password is in the request, and the core doesn’t need file-system access.

Request

Field	TypeScript type	Req.
operation	“open_password_protected_workbook_subset_from_bytes”	yes
sourceName	string	yes
sourceBytesBase64	string	yes
viewport	ViewportWindow | null	no
delimitedOpenOptions	ContractDelimitedOpenOptions | null	no
password	string	yes

Minimal JSON template

{
  "operation": "open_password_protected_workbook_subset_from_bytes",
  "sourceName": "<sourceName>",
  "sourceBytesBase64": "<sourceBytesBase64>",
  "password": "<password>"
}

open_workbook_subset

Opens a workbook subset.

Request

Field	TypeScript type	Req.
operation	"open_workbook_subset"	yes
sourceUri	string	yes
viewport	ViewportWindow | null	no
delimitedOpenOptions	ContractDelimitedOpenOptions | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · open_workbook_subset

Field	TypeScript type	Req.	Note from the contract
operation	"open_workbook_subset"	yes
subsetId	string	yes
sheetCount	number	yes
session	ContractSubsetSessionInfo	yes
readiness	ContractWorkbookReadiness	yes
formatCapabilities	ContractFormatCapabilities | null	no
xlsbDirtySaveProfile	ContractXlsbDirtySaveProfile | null	no
activeSheet	ContractActiveSheetMeta	yes
workbookSheets	ContractWorkbookSheetMeta[]	no
themeFonts	ContractWorkbookThemeFontsProjection | null	no
tableMetadata	ContractTableMetadataProjection | null	no
workbookTableMetadata	ContractTableMetadataProjection | null	no
worksheetAutoFilterMetadata	ContractWorksheetAutoFilterMetadata | null	no
directionPlaceholder	ContractDirectionPlaceholderSubset | null	no
objectStatusPlaceholder	ContractObjectStatusPlaceholderSubset | null	no
surfaceObjects	ContractSheetObject[] | null	no
objectInventory	ContractWorkbookObjectInventoryEntry[] | null	no
inkProjection	ContractReviewInkProjectionItem[] | null	no
geometry	ContractGeometrySubset	yes
recalcNeeded	boolean	yes
viewport	ViewportWindow	yes
previewCells	ContractPreviewCell[]	yes
conditionalFormattingRules	ContractConditionalRule[]	no
dataValidationMetadata	ContractDataValidationMetadata	no
frozenBandCells	ContractPreviewCell[]	no
layoutMetrics	ContractLayoutMetricsSubset | null	no
formulaTrustSnapshot	ContractFormulaTrustSnapshot | null	no
themeColorPalette	string[]	no
viewportReadiness	ContractViewportReadiness	no	Data-area readiness: you can only display it after the core has declared it ready.

Minimal JSON template

{
  "operation": "open_workbook_subset",
  "sourceUri": "file:///path/book.xlsx",
  "requestedBackend": "native-desktop"
}

open_workbook_subset_from_bytes

Opens a workbook subset from bytes.

The response will come back under a different operation’s name

For an open_workbook_subset_from_bytes request, payload.operation comes back as open_workbook_subset. Match the response to the request by its identifier, not by the operation name — why.

Request

Field	TypeScript type	Req.
operation	"open_workbook_subset_from_bytes"	yes
sourceName	string	yes
sourceBytesBase64	string	yes
viewport	ViewportWindow | null	no
delimitedOpenOptions	ContractDelimitedOpenOptions | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · open_workbook_subset

Field	TypeScript type	Req.	Note from the contract
operation	"open_workbook_subset"	yes
subsetId	string	yes
sheetCount	number	yes
session	ContractSubsetSessionInfo	yes
readiness	ContractWorkbookReadiness	yes
formatCapabilities	ContractFormatCapabilities | null	no
xlsbDirtySaveProfile	ContractXlsbDirtySaveProfile | null	no
activeSheet	ContractActiveSheetMeta	yes
workbookSheets	ContractWorkbookSheetMeta[]	no
themeFonts	ContractWorkbookThemeFontsProjection | null	no
tableMetadata	ContractTableMetadataProjection | null	no
workbookTableMetadata	ContractTableMetadataProjection | null	no
worksheetAutoFilterMetadata	ContractWorksheetAutoFilterMetadata | null	no
directionPlaceholder	ContractDirectionPlaceholderSubset | null	no
objectStatusPlaceholder	ContractObjectStatusPlaceholderSubset | null	no
surfaceObjects	ContractSheetObject[] | null	no
objectInventory	ContractWorkbookObjectInventoryEntry[] | null	no
inkProjection	ContractReviewInkProjectionItem[] | null	no
geometry	ContractGeometrySubset	yes
recalcNeeded	boolean	yes
viewport	ViewportWindow	yes
previewCells	ContractPreviewCell[]	yes
conditionalFormattingRules	ContractConditionalRule[]	no
dataValidationMetadata	ContractDataValidationMetadata	no
frozenBandCells	ContractPreviewCell[]	no
layoutMetrics	ContractLayoutMetricsSubset | null	no
formulaTrustSnapshot	ContractFormulaTrustSnapshot | null	no
themeColorPalette	string[]	no
viewportReadiness	ContractViewportReadiness	no	Data-area readiness: you can only display it after the core has declared it ready.

Minimal JSON template

{
  "operation": "open_workbook_subset_from_bytes",
  "sourceName": "book.xlsx",
  "sourceBytesBase64": "<base64>",
  "requestedBackend": "native-desktop"
}

publish_file_open_recovery

Publishes recovery on file open.

Request

Field	TypeScript type	Req.
operation	"publish_file_open_recovery"	yes
sourceUri	string	yes
destinationUri	string	yes
planId	string	yes
mode	ContractFileRecoveryMode	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · publish_file_open_recovery

Field	TypeScript type	Req.
operation	"publish_file_open_recovery"	yes
publication	ContractFileRecoveryPublication	yes

Minimal JSON template

{
  "operation": "publish_file_open_recovery",
  "sourceUri": "file:///path/book.xlsx",
  "destinationUri": "file:///path/output.xlsx",
  "planId": "<string>",
  "mode": "<ContractFileRecoveryMode>",
  "requestedBackend": "native-desktop"
}

replay_workbook_history

Replays a workbook’s history.

Request

Field	TypeScript type	Req.
operation	"replay_workbook_history"	yes
subsetId	string	yes
direction	ContractWorkbookHistoryDirection	yes
viewport	ViewportWindow | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · replay_workbook_history

Field	TypeScript type	Req.
operation	"replay_workbook_history"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
direction	ContractWorkbookHistoryDirection	yes
historyOwner	ContractWorkbookHistoryOwner	yes
undoDepth	number	yes
redoDepth	number	yes
revision	number	yes
replayed	ComputeResponsePayload	yes

Minimal JSON template

{
  "operation": "replay_workbook_history",
  "subsetId": "<subsetId>",
  "direction": "<ContractWorkbookHistoryDirection>",
  "requestedBackend": "native-desktop"
}

save_workbook_subset

Saves a workbook subset.

Request

Field	TypeScript type	Req.
operation	"save_workbook_subset"	yes
subsetId	string	yes
destinationUri	string	yes
preserveCachedValues	boolean	yes
delimitedSaveOptions	ContractDelimitedSaveOptions | null	no
xlsxSavePatch	ContractXlsxSavePatch | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · save_workbook_subset

Field	TypeScript type	Req.
operation	"save_workbook_subset"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
saveRoute	ContractCurrentSubsetSaveRoute	yes
wroteBytes	number	yes
recalcNeeded	boolean	yes

Minimal JSON template

{
  "operation": "save_workbook_subset",
  "subsetId": "<subsetId>",
  "destinationUri": "file:///path/output.xlsx",
  "preserveCachedValues": false,
  "requestedBackend": "native-desktop"
}

save_workbook_subset_to_bytes

Saves a workbook subset to bytes.

Request

Field	TypeScript type	Req.
operation	"save_workbook_subset_to_bytes"	yes
subsetId	string	yes
saveFormat	ContractFileFormat | null	no
preserveCachedValues	boolean	yes
delimitedSaveOptions	ContractDelimitedSaveOptions | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · save_workbook_subset_to_bytes

Field	TypeScript type	Req.
operation	"save_workbook_subset_to_bytes"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
saveRoute	ContractCurrentSubsetSaveRoute	yes
formulaTrustSnapshot	ContractFormulaTrustSnapshot | null	no
savedFormat	ContractFileFormat	yes
byteCount	number	yes
bytesBase64	string	yes
recalcNeeded	boolean	yes

Minimal JSON template

{
  "operation": "save_workbook_subset_to_bytes",
  "subsetId": "<subsetId>",
  "preserveCachedValues": false,
  "requestedBackend": "native-desktop"
}

synchronize_workbook_viewport

Synchronizes a workbook’s visible area.

Request

Field	TypeScript type	Req.	Note from the contract
operation	"synchronize_workbook_viewport"	yes
subsetId	string	yes
sourceUri	string	yes
viewport	ViewportWindow | null	no
recordHistory	false	yes	A view change isn’t a user edit and doesn’t go into the history.
expectedReadinessGeneration	number | null	no	Omitting this field belongs only in old code. The normal approach is to tie the display to the data generation you saw before the request.
requestedBackend	ComputeBackendKind | null	no

Response on success · synchronize_workbook_viewport

Field	TypeScript type	Req.	Note from the contract
operation	"synchronize_workbook_viewport"	yes
subsetId	string	yes
viewportReadiness	ContractViewportReadiness	yes
projection	OpenWorkbookSubsetProjectionPayload | null	no	Present only when state=ready. In responses about a deferred, canceled, superseded, or failed request, there’s never an empty state passed off as ready data.

Minimal JSON template

{
  "operation": "synchronize_workbook_viewport",
  "subsetId": "<subsetId>",
  "sourceUri": "file:///path/book.xlsx",
  "recordHistory": false,
  "requestedBackend": "native-desktop"
}

workbook_accessibility

Workbook accessibility: an inventory of issues and fixing them within given bounds.

Request

Field	TypeScript type	Req.
operation	"workbook_accessibility"	yes
subsetId	string	yes
requestId	string	yes
expectedRevision	number	yes
expectedGeneration	number	yes
readOnly	boolean	no
protected	boolean	no
intent	ContractWorkbookAccessibilityIntent	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · workbook_accessibility

Field	TypeScript type	Req.
operation	"workbook_accessibility"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractWorkbookAccessibilityResult	yes

Minimal JSON template

{
  "operation": "workbook_accessibility",
  "subsetId": "<subsetId>",
  "requestId": "<string>",
  "expectedRevision": 0,
  "expectedGeneration": 0,
  "intent": "<ContractWorkbookAccessibilityIntent>",
  "requestedBackend": "native-desktop"
}

workbook_links_manager

Links to other workbooks: an inventory of local external links and their lifecycle.

Request

Field	TypeScript type	Req.
operation	"workbook_links_manager"	yes
subsetId	string	yes
intent	ContractWorkbookLinksIntent	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · workbook_links_manager

Field	TypeScript type	Req.
operation	"workbook_links_manager"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractWorkbookLinksResult	yes

Minimal JSON template

{
  "operation": "workbook_links_manager",
  "subsetId": "<subsetId>",
  "intent": "<ContractWorkbookLinksIntent>",
  "requestedBackend": "native-desktop"
}

workbook_window_session_command

Workbook and window: what the core owns within a single contract, and which commands are projected outward.

Request

Field	TypeScript type	Req.
operation	"workbook_window_session_command"	yes
subsetId	string	yes
intent	ContractWorkbookWindowSessionAction	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · workbook_window_session_command

Field	TypeScript type	Req.
operation	"workbook_window_session_command"	yes
projection	ContractWorkbookWindowSessionProjection	yes

Minimal JSON template

{
  "operation": "workbook_window_session_command",
  "subsetId": "<subsetId>",
  "intent": "<ContractWorkbookWindowSessionAction>",
  "requestedBackend": "native-desktop"
}