Plugin upgrades
Version updates, migration ordering, capability consent and dependency constraints.
Prepare an update
Set the package's new SemVer version in signals.yaml. Check signals_version against the host, requires against installed plugin versions, and conflicts against active packages. PluginPreflightService also checks enabled dependants before an update proceeds.
Treat removing or renaming permissions, events, notification keys, settings, workflow extension IDs, tables, or callable contracts as a contract change for users and dependent plugins. Plan data migration and dependent changes explicitly; a version number alone does not rewrite stored references. requires and conflicts describe version constraints, not an automatic dependency installer.
Review capabilities
PluginCapabilitySet::diff() compares the candidate declarations with the stored grants and reports added and removed capabilities. Review the concrete capability plan produced by the install/update flow. CLI acceptance uses --accept-capabilities=<plan-hash>: it approves the exact reviewed plan, not all future changes. The UI presents its consent flow for the same package operation. Do not copy a plan hash between different artifacts or manifests.
Update order
PluginLifecycleManager::update() performs these steps after finding the installed package and passing preflight:
- Parse the candidate manifest and record the prior manifest and enabled state.
- Inside a database transaction, run pending package migrations through
PluginMigrationGuard. - Persist the new name, version and manifest, clear the disabled reason, and apply the approved capability grant and artifact digests when present.
- Seed permissions, notification types and communication templates.
- Instantiate the candidate plugin and call
onUpdate()in its package execution scope. - Align notification/template activity with the stored enabled state. If the plugin was enabled, replace its workflow extensions.
- Complete the update and refresh cached discovery/navigation data; lifecycle failure paths compensate workflow-extension replacement where needed.
onUpdate() therefore runs after migrations and the stored manifest update, including when the plugin is disabled. Updating does not automatically enable a disabled plugin. Database transaction handling cannot undo an external network side effect from a lifecycle hook; keep such hooks retry-safe.
See Data tables for migration limits and Troubleshooting for worker and discovery-cache refreshes after deployment.
Upgrading to 2.1
Set sdk: "^2.1" when adopting connections, actions, integration_principal, map sections or section refresh. Keep signals_version aligned with the independent host application version. Regenerate editor stubs from the matching framework release and rerun the sandbox checks.
New capability declarations require review and renewed consent. An unchanged 2.0 manifest preserves its capability hash. New or changed OAuth scopes/endpoints can require reconnecting; principal permission and warehouse grants must be explicitly approved and can be revoked immediately. Background work has no implicit interactive user: opt into the integration identity only where declared.
Version 1 events retain their exact bytes and may contain unguarded DTOs; they are deprecated in favour of payloadVersion: 2 envelopes with guarded data. Array slot callbacks still carry raw records by default. Adopt typed SlotContext; hosts can opt into plugins.slot_context_scalar_only, with removal of raw records deferred to a future major. These defaults are unchanged in 2.1.
Channel OAuth Connect continues to use GET. New generic connection authorization uses POST. External payments post using the current finance date; a supplied value date is retained on the receipt, without changing core finance posting semantics. Leaflet is pinned with SRI through a CDN; tenants may configure HTTPS tile templates or disable tiles, keeping the accessible location table available.
Warehouse scope tightening
Account reads and lists now respect the acting user's accessible warehouses, including SDK 2.0 plugins. Restricted users and users without an account membership see unassigned accounts plus accounts in their accessible warehouses. Integration identities apply their granted warehouse scope to all warehouse-related reads, lists and v2 event data. Identity updates also require the entity read permission and granted warehouse; ordinary user update behavior is unchanged.
2.1 → 2.2
SDK 2.2 is additive. New external refund, reversal, credit allocation and PO billing-marker operations require sdk: ^2.2. Existing payments.record_external calls now use eligible external value dates for ledger posting. See data access for UTC lock, source-floor, carrying-balance and FX fallback rules. Existing receipt hashes remain unchanged, and receipts recorded before SDK 2.2 replay stored results without new posting-date keys. Credit allocation rejects value_date and omits it from results; credits retain their existing tax dates; PO billing markers do not post to the ledger.
Correction kinds are retained in external payment mapping metadata after receipt retention. All external operation replays validate the actor, connection and payload before returning the stored result, ahead of current scoped record lookups.