Protection and review

Sheet and workbook protection, range permissions, protection auditing, change tracking, comments, and ink annotations. Terms are in the glossary.

Operations on this page — 8

• apply_track_insert_delete
• apply_track_visibility
• protected_ranges_permissions
• protection_inspector_audit
• review_annotations_lifecycle
• review_ink_lifecycle
• set_sheet_protection_bounded
• workbook_protection_lifecycle

apply_track_insert_delete

Applies tracking of insertions and deletions.

Request

Field	TypeScript type	Req.
operation	"apply_track_insert_delete"	yes
expectedRevision	number | null	no
subsetId	string	yes
sheetKey	string	yes
axis	ContractTrackAxis	yes
index	number	yes
action	ContractTrackStructureAction	yes
scope	CellRange | null	no
count	number	no
insertedHeaderText	string | null	no
viewport	ViewportWindow | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · apply_track_insert_delete

Field	TypeScript type	Req.
operation	"apply_track_insert_delete"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
supportedSubset	string	yes
delta	DeltaSummary	yes
axis	ContractTrackAxis	yes
index	number	yes
action	ContractTrackStructureAction	yes
scope	CellRange | null	no
count	number	yes
changedRows	number[]	yes
changedColumns	number[]	yes
shiftedCellCount	number	yes
removedCellCount	number	yes
trackStructureClaim	"live_verified"	yes
structureScope	| “active_visible_value_track_current_sheet” | “active_visible_value_and_simple_formula_insert_current_sheet” | “active_visible_value_and_simple_formula_structure_current_sheet” | “table_scoped_sparse_structure_current_sheet”	yes
formulaReferenceRewriteClaim	| “no” | “insert_only_bounded_same_sheet_refs” | “bounded_same_sheet_refs”	yes
mergeReferenceRewriteClaim	"no" | “bounded_track_merge_refs”	yes
workbookHistory	ContractWorkbookHistoryProjection	yes
dirtyCellCount	number	yes
currentSourceSaveReadiness	ContractCurrentSourceSaveReadiness | null	no
activeSheet	ContractActiveSheetMeta	yes
geometry	ContractGeometrySubset	yes
recalcNeeded	boolean	yes
viewport	ViewportWindow	yes
previewCells	ContractPreviewCell[]	yes
layoutMetrics	ContractLayoutMetricsSubset	yes

Minimal JSON template

{
  "operation": "apply_track_insert_delete",
  "subsetId": "<subsetId>",
  "sheetKey": "<sheetPath>",
  "axis": "<ContractTrackAxis>",
  "index": 0,
  "action": "<ContractTrackStructureAction>",
  "requestedBackend": "native-desktop"
}

apply_track_visibility

Applies the visibility of tracked changes.

Request

Field	TypeScript type	Req.
operation	"apply_track_visibility"	yes
subsetId	string	yes
sheetKey	string	yes
axis	ContractTrackAxis	yes
visibilityOwner	ContractTrackVisibilityOwner	no
index	number | null	no
indices	number[]	no
replaceOwnerProjection	boolean	no
hidden	boolean	yes
viewport	ViewportWindow | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · apply_track_visibility

Field	TypeScript type	Req.
operation	"apply_track_visibility"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
supportedSubset	string	yes
delta	DeltaSummary	yes
axis	ContractTrackAxis	yes
index	number	yes
hidden	boolean	yes
changedRows	number[]	yes
changedColumns	number[]	yes
hiddenRows	number[]	yes
manualHiddenRows	number[]	yes
filterHiddenRows	number[]	yes
dirtyCellCount	number	yes
currentSourceSaveReadiness	ContractCurrentSourceSaveReadiness | null	no
activeSheet	ContractActiveSheetMeta	yes
geometry	ContractGeometrySubset	yes
recalcNeeded	boolean	yes
viewport	ViewportWindow	yes
previewCells	ContractPreviewCell[]	yes
layoutMetrics	ContractLayoutMetricsSubset	yes

Minimal JSON template

{
  "operation": "apply_track_visibility",
  "subsetId": "<subsetId>",
  "sheetKey": "<sheetPath>",
  "axis": "<ContractTrackAxis>",
  "hidden": false,
  "requestedBackend": "native-desktop"
}

protected_ranges_permissions

Permissions on protected ranges: who’s allowed to do what inside a protected sheet.

Request

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

Response on success · protected_ranges_permissions

Field	TypeScript type	Req.
operation	"protected_ranges_permissions"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractProtectedRangesResult	yes

Minimal JSON template

{
  "operation": "protected_ranges_permissions",
  "subsetId": "<subsetId>",
  "intent": "<ContractProtectedRangesIntent>",
  "requestedBackend": "native-desktop"
}

protection_inspector_audit

Inspecting workbook protection and a plan of tracked changes within given bounds.

Request

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

Response on success · protection_inspector_audit

Field	TypeScript type	Req.
operation	"protection_inspector_audit"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractProtectionAuditResult	yes

Minimal JSON template

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

review_annotations_lifecycle

Notes and comments: identification and lifecycle — the classic notes and comments that live inside the workbook.

Request

Field	TypeScript type	Req.
operation	"review_annotations_lifecycle"	yes
subsetId	string	yes
requestId	string	yes
expectedRevision	number	yes
expectedGeneration	number	yes
nowUtc	string	yes
readOnly	boolean	no
protected	boolean	no
state	ContractReviewAnnotationsState	yes
intent	ContractReviewAnnotationsIntent	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · review_annotations_lifecycle

Field	TypeScript type	Req.
operation	"review_annotations_lifecycle"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractReviewAnnotationsResult	yes
workbookHistory	ContractWorkbookHistoryProjection	yes

Minimal JSON template

{
  "operation": "review_annotations_lifecycle",
  "subsetId": "<subsetId>",
  "requestId": "<string>",
  "expectedRevision": 0,
  "expectedGeneration": 0,
  "nowUtc": "<string>",
  "state": "<ContractReviewAnnotationsState>",
  "intent": "<ContractReviewAnnotationsIntent>",
  "requestedBackend": "native-desktop"
}

review_ink_lifecycle

Ink annotations: an inventory of existing ones, and deleting them in one atomic action.

Request

Field	TypeScript type	Req.
operation	"review_ink_lifecycle"	yes
subsetId	string	yes
scope	ContractReviewInkDeleteScope	yes
sheetPath	string | null	no
expectedRevision	number	yes
readOnly	boolean	no
viewport	ViewportWindow | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · review_ink_lifecycle

Field	TypeScript type	Req.
operation	"review_ink_lifecycle"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
scope	ContractReviewInkDeleteScope	yes
deletedCount	number	yes
byteCount	number	yes
identityLedger	ContractReviewInkIdentityLedgerEntry[]	yes
removedPartCount	number	yes
removedRelationshipCount	number	yes
removedContentTypeOverrideCount	number	yes
preservedInkParts	ContractReviewInkPreservedPart[]	yes
preexistingOrphanCount	number	yes
orphanCount	number	yes
newOrphanCount	number	yes
objectInventory	ContractWorkbookObjectInventoryEntry[]	yes
inkProjection	ContractReviewInkProjectionItem[]	yes
workbookHistory	ContractWorkbookHistoryProjection	yes
activeSheet	ContractActiveSheetMeta	yes
workbookSheets	ContractWorkbookSheetMeta[]	yes
geometry	ContractGeometrySubset	yes
viewport	ViewportWindow	yes
previewCells	ContractPreviewCell[]	yes
surfaceObjects	ContractSheetObject[]	yes
layoutMetrics	ContractLayoutMetricsSubset	no

Minimal JSON template

{
  "operation": "review_ink_lifecycle",
  "subsetId": "<subsetId>",
  "scope": "<ContractReviewInkDeleteScope>",
  "expectedRevision": 0,
  "requestedBackend": "native-desktop"
}

set_sheet_protection_bounded

Sets sheet protection within given bounds.

Request

Field	TypeScript type	Req.
operation	"set_sheet_protection_bounded"	yes
subsetId	string	yes
sheetKey	string	yes
protected	boolean	yes
allowedActions	ContractSheetProtectionAllowedAction[] | null	no
password	string | null	no
sessionAction	ContractSheetProtectionSessionAction | null	no
viewport	ViewportWindow | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · set_sheet_protection_bounded

Field	TypeScript type	Req.
operation	"set_sheet_protection_bounded"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
supportedSubset	string	yes
delta	DeltaSummary	yes
changedSheet	ContractActiveSheetMeta	yes
previousProtected	boolean	yes
previousAllowedActions	ContractSheetProtectionAllowedAction[] | null	no
previousPasswordProtected	boolean	yes
protected	boolean	yes
allowedActions	ContractSheetProtectionAllowedAction[] | null	no
passwordProtected	boolean	yes
packageProtected	boolean	yes
effectiveProtected	boolean	yes
sessionUnlocked	boolean	yes
sessionAction	ContractSheetProtectionSessionAction | null	no
activeSheet	ContractActiveSheetMeta	yes
sheetCount	number	yes
workbookSheets	ContractWorkbookSheetMeta[]	yes
geometry	ContractGeometrySubset	yes
recalcNeeded	boolean	yes
viewport	ViewportWindow	yes
previewCells	ContractPreviewCell[]	yes
layoutMetrics	ContractLayoutMetricsSubset | null	no
workbookHistory	ContractWorkbookHistoryProjection	yes
sheetProtectionClaim	"live_verified"	yes
protectionScope	"same_workbook_sheetProtection_metadata"	yes
passwordProtectionClaim	"live_verified"	yes

Minimal JSON template

{
  "operation": "set_sheet_protection_bounded",
  "subsetId": "<subsetId>",
  "sheetKey": "<sheetPath>",
  "protected": false,
  "requestedBackend": "native-desktop"
}

workbook_protection_lifecycle

Protecting the entire workbook: setting it, removing it, and checking its state.

Request

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

Response on success · workbook_protection_lifecycle

Field	TypeScript type	Req.
operation	"workbook_protection_lifecycle"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractWorkbookProtectionResult	yes

Minimal JSON template

{
  "operation": "workbook_protection_lifecycle",
  "subsetId": "<subsetId>",
  "intent": "<ContractWorkbookProtectionIntent>",
  "requestedBackend": "native-desktop"
}