Catalog lineage
Some of the records in your workspace are written from scratch by your team. Others arrive ready-made, imported from a published catalog. Catalog lineage is the back-reference for that second category: a per-record provenance entry that says where this came from, when it arrived, and whether the upstream has since moved on.
A worked scenario: a maritime logistics operator
A maritime logistics operator installs a published controls package, “Port-Operations Baseline v3.2,” into a new organization. The install creates 47 controls, 12 indicators, and 6 assessment templates inside that organization. Each of those local records gets a catalog template lineage entry recording:
- the source catalog provider (the publisher of the package)
- the source template id and version
- the source template hash
- the source pack id and version
- when it was acquired (
acquiredAt) and by which member - the acquisition method (installed, imported, copied)
- its lineage status (active)
Above all 65 records, a single catalog package installation record stands as the parent: the install event itself, with installedObjectRefs pointing at every record the install created.
Six months later, the operator’s compliance lead opens any of those controls and sees, in the right-hand panel, that this control was installed from Port-Operations Baseline v3.2 by Layla, on 2026-03-14, and is currently active lineage. Clicking the lineage link opens a side panel with the source details.
What lineage tells you
For each imported record, lineage records:
| Field | What it answers |
|---|---|
sourceCatalogProvider | Which catalog this came from. |
sourceTemplateId + sourceTemplateVersion | Which template, at which version, on the upstream side. |
sourceTemplateHash | A content fingerprint so you can tell if the upstream content has changed even when the version label hasn’t. |
sourcePackId + sourcePackVersion | Which pack the template belonged to. |
acquisitionMethod | How it arrived (install, import, copy). |
acquiredAt + acquiredByMemberUserId | When and who. |
status | active, superseded, or detached. |
mappingSnapshot | The mapping rules used at install (for templates that have configurable mapping). |
importSnapshot | The raw source-side snapshot at install (preserved so you can diff against upstream later). |
The same fields appear, with package-shaped variants, on the catalog package installation record above the templates.
Lineage statuses
A lineage entry is always in one of three states:
- active: the local record is still linked to the upstream source. Updates from upstream can be considered.
- superseded: this lineage entry was replaced by a newer one (for example, the operator accepted v3.3 of the source template, which created a new lineage entry pointing at the new version; the old one is closed out as superseded and carries
supersededByLineageId). - detached: the operator decided to break the link with upstream. The local record stays, but no upstream updates will be considered. Detaching requires a reason.
Statuses for the package installation record mirror this pattern:
- active: the install is still recognized.
- superseded: a newer package install replaces this one.
- disabled: the install is suspended without breaking the link (use during incident triage).
- detached: the link is broken; local records remain but no longer accept upstream updates.
Detaching is not the same as deleting. The local records remain in the workspace and continue to function. Detach disconnects the upstream relationship; it does not remove the records themselves.
A worked scenario: superseding versus detaching
A regional health insurance carrier installed a “Member-Communications Privacy v1.4” pack. Six months on, the publisher releases v2.0 with structural changes.
The carrier’s privacy team reviews the diff and decides to accept v2.0 for most templates, but rewrites one of them locally to fit a state-level constraint the catalog doesn’t cover. The result:
- For 11 of 12 templates, accepting v2.0 creates new active lineage entries pointing at v2.0 of each source template. The old v1.4 lineage entries are marked superseded and reference their replacements.
- For the 12th template (the one they rewrote locally), the team chose detach. The lineage entry is marked detached with a reason (“State-X requires explicit member opt-out language not present in the catalog v2.0 template”). The local template stays and keeps being used; it just no longer pretends to track upstream.
Anyone reviewing this work later sees both decisions in lineage without needing to read incident notes.
How lineage is created
Lineage is not created by hand in the usual case. It’s written automatically when:
- a published catalog pack is installed into the organization (creates one package installation record and many template lineage records)
- a template is imported standalone (creates a template lineage record without a parent package installation)
- a copy operation deliberately preserves provenance
Editing the catalog source fields after the fact is not allowed. The whole point of lineage is to be a faithful, untouched record of what arrived from upstream.
Where you see lineage in the product
- On any imported record’s detail page, in the provenance side panel.
- On the catalog management surface (when present), in the package installation view.
- In governance trace edges (lineage is one of the relationship kinds the trace graph can show).
Acquisition methods
The acquisition method captures how the local record came to exist:
- install: arrived as part of a published package installation.
- import: imported standalone, outside a package.
- copy: a local-to-local copy that deliberately preserved provenance from the original.
The method is set at acquisition time and is not editable after.
A worked scenario: an upstream content change
A higher-education ministry registered the source template “Faculty-Conduct Annual Attestation v2.1” into 9 affiliated universities. The publisher pushes v2.1.1, a small wording fix. The hash changes.
Because every install carries sourceTemplateHash, each university’s lineage entry for that template now shows that the source content has drifted from the installed copy. The compliance lead at each university can review the diff and decide individually:
- Accept the update (creates a superseded + new active pair, automatic).
- Continue using the installed version (no change; the drift is visible in the panel as a notice).
- Detach (with a reason).
The decision is local to each organization. Lineage doesn’t force a workspace to take an update.
Permissions
Reading lineage requires the catalog-lineage.view permission. Acting on lineage (superseding, detaching, disabling installations) requires the catalog-lineage manage permission. Both are governed by the roles & permissions model the rest of the workspace uses.
Related
- Trace graph, which can render lineage relationships visually alongside other governance edges.
- Governance trace overview, the section index.
- Audit log, for the timestamped record of who installed, superseded, or detached.