Extension Version Management
View installation state across all content kinds, review workflow impact, and update extensions from an extension's Version & security tab.
An extension's row on Settings → Platform → Extensions → Installed (and its sheet's Includes and Version & security tabs) is the single place to track which version is installed, see per-content-kind install state, and apply updates. For the full versioning model from an extension author's perspective — semver rules, the release checklist, and how pins/policies decide what runs — see Extension versioning. When an extension extension has an update available, its row on the Extensions → Installed tab shows it in the version column — 1.3.0 → 1.4.0 — never on the state line, so a pending update can't hide a failing credential. The update itself is reviewed and applied in the extension's Version & security tab.
Update behavior by content type
Not every kind of extension content updates the same way — the platform applies the least automation that is safe for each kind. This table is the mental model; the sections below detail each.
| Content type | How updates apply | Why |
|---|---|---|
| Static reference data sources (inline data, no external calls) | Automatic on sync — installed when an extension update reaches your catalog, unless the extension's policy is Manual. | Additive, makes no external calls, and can't overwrite your data — the safest kind. |
| External (polling) data sources | Install from Analytics → Marketplace — Update to vX reconciles the extension's full set. | A new source begins calling an external system, so installing it is your decision. |
| Ontology & KB domains | New schema items apply automatically on sync in every existing workspace environment where the extension is already installed; changes to existing items, and new KB domains, apply when you click Update extension. | Adding new object/link types is safe; modifying or removing them can affect bound tables, analytics, and the graph. |
| Process flows | Automatic — always the latest catalog version. | A template only appears in the gallery; it runs nothing until a workspace opts in. |
| Extensions | Per connection: manual (default), or opt-in auto_patch / auto_minor; breaking changes always held. | Executable vendor code + credentials + egress — the highest-risk kind. |
| Workflows | Deployed per environment from the agentic Extensions page; re-deploy to update. | You choose which environment runs which version. |
| Notebooks | Stored at install; materialize / update per workspace in Analytics. | Nothing runs until you materialize it. |
Safety guarantees, always: an automatic apply only ever adds — it never deletes your data, never overwrites a source or type you already have, never starts a new external call, and never runs new code without you. A breaking extension change is never applied automatically — it is flagged and waits for your review.
Each extension has an update policy (default Automatic). Additive, no-egress content — static reference data sources and new ontology schema items — installs automatically when an extension update reaches your catalog. Set an extension's policy to Manual to review every update yourself; anything that calls an external system, runs code, or changes an existing item always keeps its review step regardless of policy. So you never miss a withheld update, the extension's Includes tab flags declared-but-uninstalled data sources ("N available, not installed"), and the map shows a not provisioned state when a layer's backing table is missing — instead of a silent "(0)".
Seeing where an extension is used
The catalog table's In use column shows what each installed extension actually produced in your organization:
- Workflows — workflows deployed from the extension, per workspace environment. Click a workflow to open it in Agentic.
- Process flows — live process-flow instances created from the extension's templates. The count is the true total; the popover lists the 25 most recent. Click an instance to open it in Agentic.
- Data sources — data sources installed from the extension. Click to open the data sources page in Analytics.
A dash (—) means the extension is in your catalog but nothing currently uses it — a useful signal before retiring an extension.
Expanding an extension row shows the same information in detail, plus Workflows using this extension's extensions: workflows anywhere in your organization whose blocks call an extension this extension installed. This is the same impact analysis the update flow runs — shown at all times, so you can assess blast radius before retiring or updating.
If a panel shows State unavailable, one backing service could not be reached; the other panels remain accurate.
Install State Column
Each row in the Catalog tab shows one extension at its highest available version. The Install state column shows the most important state across all of that extension's content kinds:
| State | Meaning |
|---|---|
| Update available | At least one content kind has a newer version in the catalog than what is currently installed. |
| Installed | All installed content kinds are current (no update needed). |
| Not installed | No content from this extension has been installed in your organization. |
When an update is available, the version column shows the installed version alongside the latest: for example v1.1.0 → v1.1.1.
For ontology content, this organization-level state is deliberately strict. It is shown only after the platform reads every expected workspace environment and finds the same extension version, ontology identity, catalog/source provenance, and normalized manifest in each one. A missing or divergent environment makes the ontology panel report State unavailable instead of choosing one row and presenting it as organization-wide truth.
Expanded Row — Per-Kind State
Click any row to expand it and see the install state broken down by content kind:
Extensions
One line per vendor included in the extension. Shows the installed version and whether an update is pending. The update check is based on the artifact hash: if the published artifact differs from what is installed, an update is available.
Ontology and KB Domains
Shows one representative installed extension version and the date it was last applied, but only after all existing workspace environments pass the consistency check above. An organization-wide install or update fans out to every existing environment; an install/update from Analytics → Marketplace targets only the active environment.
Consistency includes the catalog row, extension-source ID and entry reference, and the complete normalized manifest snapshot. Environment-local revision IDs and timestamps are expected to differ and are not used for version comparison. The source fields can be empty for legacy/manual installs, but kernel-backed reads always return the manifest snapshot and preserve any available provenance.
For API consumers, InstalledExtensionRow remains source-compatible: sourceId
and sourceEntryRef are additive optional-nullable fields, and legacy TypeScript
fixtures may still omit manifestSnapshot as an input convenience. A
kernel-backed installed row always supplies the complete normalized
manifestSnapshot and returns the two provenance fields (possibly null);
clients must not replace the snapshot with a hash or a reconstructed subset.
Workflows
Shows one row per workspace environment in which this extension's workflows have been deployed. Each row includes:
- The workspace environment name.
- The installed extension version, or version unknown if the workflow was deployed before version tracking was introduced. "Version unknown" is harmless — the workflow is running, but its extension version cannot be compared.
Deploying a workflow to a workspace is a separate action on the agentic Extensions page. The extension's Includes tab shows workflows that were already deployed; "not deployed" environments are omitted from the list.
Data Sources
Shows one row per workspace environment in which a data source from this extension is installed. Installing and updating data sources happens on Analytics → Marketplace: when a newer extension version is in the catalog, each installed source there shows an Update to vX action that reconciles the whole extension's data-source set — existing sources are refreshed, sources added by the new version are installed, and sources it removed are pruned. See Extensions.
Process Flows
Process flows always track the latest catalog version — they do not have a fixed installed version. The expanded row shows a badge confirming this. There is no update action for process flows; they automatically use the content from the newest active catalog row for this extension.
Updating a Extension
When at least one content kind has an update available, an update bar appears at the top of the expanded row.
Click the extension in the Catalog tab to open the expanded view. If there is an update available, the update bar shows the target version (for example, Update to v1.1.1) and a summary of which extensions will be affected.
For extensions that include extension content, the platform automatically loads a workflow impact analysis — showing which workflows reference tools from this extension's extensions. The Update extension button stays disabled until this analysis has finished loading.
If the impact analysis fails to load, the Update extension button remains disabled. Check your network connection or contact your platform administrator.
The platform diffs the installed and target extension manifests and lists detected breaking changes directly in the update bar: removed tools, new required inputs, changed input/output types, or auth-mode changes — each annotated with the tool it affects.
Two warning levels can appear:
- Potentially breaking (amber) — the update is a major version bump, or the manifest diff found breaking changes that the author declared correctly.
- Breaking changes in a non-major update (red) — the manifest diff found breaking changes but the version bump is only a minor or patch. Treat this with extra care and contact the extension author.
Review the affected-workflows list together with these findings before proceeding.
The platform installs the latest catalog version for this extension. Extension code stays organization-owned; ontology and KB content fan out to every existing workspace environment. A success toast confirms the update only after all ontology targets succeed. If one target fails, successful targets remain applied and a retry safely revisits the operation.
Per-environment content is updated from its own surface: data sources from Analytics → Marketplace (where the update reconciles the extension's full source set — see Data Sources above), and workflows by re-deploying from the agentic Extensions page.
Clicking Update extension also moves your organization's version pin for the extension's extensions: in-flight workflow runs finish on the version they started with, and new runs use the updated version.
Version Pinning and Update Policies
Installed extension versions are pinned per connection. A newer version arriving in your catalog (for example via a Git extension source sync) is staged but inert — nothing changes about what your workflows execute until the pin moves. The pin moves in one of two ways:
- Manually — you click Update extension after the impact review (the default for every connection).
- Automatically — a connection can opt in to auto-updates via its update policy:
| Policy | Behavior |
|---|---|
manual (default) | Updates are staged only; you apply them from the extension's Version & security tab. |
auto_patch | Patch releases (1.1.0 → 1.1.1) apply automatically when the manifest diff finds no breaking changes. |
auto_minor | Patch and minor releases apply automatically when the manifest diff finds no breaking changes. |
Auto-updates never apply when the manifest diff detects a breaking change — the connection is flagged (update blocked: breaking_diff) and the update waits for your manual review in the extension's Version & security tab. Major version bumps always require a manual update.
SDK Compatibility Errors
Code releases are compiled against a specific version of the Scrydon authoring SDK. If an archive was built against an SDK contract the platform no longer (or does not yet) support, you will see:
- At install time: the extension install fails with
extension_contract_incompatibleand a message naming the contract versions involved. - At run time: tools from the archive fail with
BUNDLE_CONTRACT_INCOMPATIBLEinstead of executing.
Both messages mean the same thing: the archive needs to be republished with a current @scrydon/sdk-authoring release. If you author the extension, rebuild it with the latest SDK and publish a new version; if it comes from a vendor, ask them for an updated release. Archives built against the immediately previous SDK contract continue to work — the platform translates for them automatically.
Other Live Catalog Versions
At the bottom of the expanded row, Other live catalog versions lists any older versions of this extension that are still present in your catalog (for example, if a previous version was installed and the catalog was not cleaned up). These entries are informational — they show what is available but are not the active installed version.
Finding Updates for Installed Extensions
When an extension extension has an update available, the vendor's row on Settings → Platform → Extensions → Installed shows it in the version column as 1.3.0 → 1.4.0. The state line stays free for anything that needs a human. Opening the row leads to its Version & security tab, where the update card says what changes and what carries over, and you apply it there.
The Add extension catalog only offers what is not installed yet; an installed extension extension is the vendor's own row there, muted in place, with Manage opening its sheet.