VBA and macros

Project inspection, planning and running, status, cancellation and rollback, macro trust, and the approved list. Terms are in the glossary.

A macro never runs in the workbook itself: the core runs it on a copy, shows a preview of the changed cells, and carries the result over only after confirmation; the commit can be rolled back. External objects that a macro creates through CreateObject go through the core’s broker: everything is denied by default, a person grants the needed classes for a single run (externalObjectGrants in plan_vba_execution and start_vba_execution), and every call goes into the log—whether it was executed or rejected.

Inspection works everywhere; running doesn’t

Inspecting the project, listing entry points, and planning and previewing edits are all just parsing, and that runs in any build. Actually running a macro is done by the automation provider, and it isn’t compiled into every build: the desktop and server processor have it; the browser build and the mobile core don’t.

Where it’s absent, the run operations refuse the same way for any workbook — with the code automation-provider-unavailable, before the file is even read. This is a property of the build, not of the launch mode or the workbook.

Operations on this page — 12

• cancel_vba_execution
• commit_vba_execution
• get_vba_execution_status
• inspect_vba_project
• list_approved_macros
• list_vba_entrypoints
• macro_trust_lifecycle
• plan_vba_execution
• preview_vba_mutations
• rollback_vba_execution
• run_approved_macro
• start_vba_execution

cancel_vba_execution

Cancels a VBA run.

Request

Field	TypeScript type	Req.
operation	"cancel_vba_execution"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · cancel_vba_execution

Field	TypeScript type	Req.
operation	"cancel_vba_execution"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
outcome	VbaExecutionOutcome	yes

Minimal JSON template

{
  "operation": "cancel_vba_execution",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

commit_vba_execution

Commits a VBA run.

Request

Field	TypeScript type	Req.
operation	"commit_vba_execution"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · commit_vba_execution

Field	TypeScript type	Req.
operation	"commit_vba_execution"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
committed	VbaMutationPreview	yes

Minimal JSON template

{
  "operation": "commit_vba_execution",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

get_vba_execution_status

Gets the state of a VBA run.

Request

Field	TypeScript type	Req.
operation	"get_vba_execution_status"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · get_vba_execution_status

Field	TypeScript type	Req.
operation	"get_vba_execution_status"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
outcome	VbaExecutionOutcome	yes

Minimal JSON template

{
  "operation": "get_vba_execution_status",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

inspect_vba_project

Inspects a VBA project.

Request

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

Response on success · inspect_vba_project

Field	TypeScript type	Req.
operation	"inspect_vba_project"	yes
subsetId	string	yes
inspection	VbaProjectInspection	yes

Minimal JSON template

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

list_approved_macros

Returns the list of approved macros.

Request

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

Response on success · list_approved_macros

Field	TypeScript type	Req.	Note from the contract
operation	"list_approved_macros"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
macros	ApprovedMacroDescriptor[]	yes
policyNote	string	yes	Explains why the list came out the way it did. An empty list means one of two things, and this field tells them apart: either the workbook has no readable VBA project — there’s nothing to run — or the project exists, but none of its procedures made it onto the allowed list. What’s actually in the workbook is answered by the list_vba_entrypoints and plan_vba_execution operations.

Minimal JSON template

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

list_vba_entrypoints

Returns the list of VBA entry points.

Request

Field	TypeScript type	Req.	Note from the contract
operation	"list_vba_entrypoints"	yes
subsetId	string	yes
userRunnableOnly	boolean	no	Only the macros the user sees in Excel’s “Macros” dialog.
requestedBackend	ComputeBackendKind | null	no

Response on success · list_vba_entrypoints

Field	TypeScript type	Req.	Note from the contract
operation	"list_vba_entrypoints"	yes
subsetId	string	yes
entrypoints	VbaEntrypointDescriptor[]	yes	The procedures included in the response: either every parsed procedure in the project, or, with userRunnableOnly, only the ones visible in the “Macros” dialog. This list’s length depends on the request and says nothing about the workbook itself; the two fields below exist for that.
userRunnable	number	yes	How many macros the user could run from the “Macros” dialog, and how many of them the core runs directly. These are properties of the workbook itself: they’re not recomputed from the returned list, so narrowing the list doesn’t lower these numbers. inspect_vba_project returns the same values.
userRunnableNative	number	yes

Minimal JSON template

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

macro_trust_lifecycle

Macro trust within the session — what lives in Excel’s “Trust Center”.

Request

Field	TypeScript type	Req.
operation	"macro_trust_lifecycle"	yes
subsetId	string	yes
intent	ContractMacroTrustIntent	yes
readOnly	boolean	no
protectedView	boolean	no
trustedLocation	boolean	no
modifiedAfterSignatureRisk	boolean	no
requestedBackend	ComputeBackendKind | null	no

Response on success · macro_trust_lifecycle

Field	TypeScript type	Req.
operation	"macro_trust_lifecycle"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
result	ContractMacroTrustResult	yes

Minimal JSON template

{
  "operation": "macro_trust_lifecycle",
  "subsetId": "<subsetId>",
  "intent": "<ContractMacroTrustIntent>",
  "requestedBackend": "native-desktop"
}

plan_vba_execution

Plans a VBA run.

Request

Field	TypeScript type	Req.	Note from the contract
operation	"plan_vba_execution"	yes
subsetId	string	yes
entrypoint	string	yes	A name of the form Module.Procedure — the only way to address an entry point.
activeSheet	string	yes
instructionBudget	number	no	The instruction-count limit for a single run. Without this field, the session’s default value is used.
requestedBackend	ComputeBackendKind | null	no

Response on success · plan_vba_execution

Field	TypeScript type	Req.
operation	"plan_vba_execution"	yes
subsetId	string	yes
plan	VbaExecutionPlan	yes

Minimal JSON template

{
  "operation": "plan_vba_execution",
  "subsetId": "<subsetId>",
  "entrypoint": "<string>",
  "activeSheet": "<string>",
  "requestedBackend": "native-desktop"
}

preview_vba_mutations

Builds a preview: edits from VBA.

Request

Field	TypeScript type	Req.
operation	"preview_vba_mutations"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · preview_vba_mutations

Field	TypeScript type	Req.
operation	"preview_vba_mutations"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
preview	VbaMutationPreview	yes

Minimal JSON template

{
  "operation": "preview_vba_mutations",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

rollback_vba_execution

Rolls back a VBA run.

Request

Field	TypeScript type	Req.
operation	"rollback_vba_execution"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
requestedBackend	ComputeBackendKind | null	no

Response on success · rollback_vba_execution

Field	TypeScript type	Req.	Note from the contract
operation	"rollback_vba_execution"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes
restoredCells	number	yes	How many cells were restored to their previous values on rollback. Zero is a perfectly valid answer: a run that changed no cells at all rolls back the same way as one that changed a thousand.

Minimal JSON template

{
  "operation": "rollback_vba_execution",
  "subsetId": "<subsetId>",
  "sessionId": "<VbaExecutionSessionId>",
  "requestedBackend": "native-desktop"
}

run_approved_macro

Runs an approved macro.

Request

Field	TypeScript type	Req.
operation	"run_approved_macro"	yes
subsetId	string	yes
macroId	string	yes
viewport	ViewportWindow | null	no
requestedBackend	ComputeBackendKind | null	no

Response on success · run_approved_macro

Field	TypeScript type	Req.
operation	"run_approved_macro"	yes
subsetId	string	yes
session	ContractSubsetSessionInfo	yes
macro	ApprovedMacroDescriptor	yes
delta	DeltaSummary	yes
changedKeys	string[]	yes
highlightCellKeys	string[]	yes
statusMessage	string	yes
activeSheet	ContractActiveSheetMeta	yes
geometry	ContractGeometrySubset	yes
recalcNeeded	boolean	yes
viewport	ViewportWindow	yes
previewCells	ContractPreviewCell[]	yes

Minimal JSON template

{
  "operation": "run_approved_macro",
  "subsetId": "<subsetId>",
  "macroId": "<string>",
  "requestedBackend": "native-desktop"
}

start_vba_execution

Starts a VBA run.

Request

Field	TypeScript type	Req.	Note from the contract
operation	"start_vba_execution"	yes
subsetId	string	yes
entrypoint	string	yes
activeSheet	string	yes
instructionBudget	number	no
shownPlanId	string	no	The identifier of the plan you showed the user before running it. Without this field, the request is planned and run right away — as before. With it, one extra check is added: the plan described by the request must match the one shown, or the refusal automation-plan-stale comes back. This field is exactly what gives the shown plan any meaning: without it, you could show the user one set of run conditions and submit a different one, and the contract would never notice.
requestedBackend	ComputeBackendKind | null	no

Response on success · start_vba_execution

Field	TypeScript type	Req.	Note from the contract
operation	"start_vba_execution"	yes
subsetId	string	yes
sessionId	VbaExecutionSessionId	yes	Always present in the response, even when there’s nothing to roll back after the run. The identifier is issued before the run and names it regardless; if there’s nothing to roll back, rollback_vba_execution honestly responds with automation-session-unknown.
outcome	VbaExecutionOutcome	yes	Right after launch, running. Later status requests return either progress or the run’s outcome.

Minimal JSON template

{
  "operation": "start_vba_execution",
  "subsetId": "<subsetId>",
  "entrypoint": "<string>",
  "activeSheet": "<string>",
  "requestedBackend": "native-desktop"
}