Skip to Content
Welcome to the Novantra documentation.
GuidesGovernanceTrace & LineageTrace graph

Trace graph

The trace graph is a panel that appears on a governed record’s detail page and answers one question: what else in the system touches this record? Up the chain, down the chain, and across modules.

A worked scenario: an upstream chemical supplier

A specialty chemicals manufacturer is being audited for its hazardous materials handling program. The auditor lands on a single operational control named “Hazardous material storage temperature monitoring.”

From that control’s detail page, opening the trace graph panel surfaces (depth 1):

  • incoming edges: two framework requirements that the control covers, three risks the control mitigates, one assurance engagement that tested the control last quarter.
  • outgoing edges: four pieces of evidence attached to it (calibration logs, sensor placement diagram, incident drill report, vendor SLA), two indicators that monitor it, one finding from the most recent assessment that contradicts a sensor placement claim.

Increasing the depth to 2 expands the picture: the finding’s verification request, the responsible duty assignment, the open exception that postpones a sensor relocation, and the source assessment that produced the finding.

The auditor doesn’t need to know the system schema. They follow the graph the way they’d follow citations in a report.

A trace link is a neutral, typed edge between two records anywhere in the workspace. Each edge carries:

  • a source (module, resource type, record id, optional version id)
  • a target (module, resource type, record id, optional version id)
  • a relationship kind (a short label that describes the edge)
  • an optional strength annotation
  • an optional snapshot of the source record at the time the link was made

That’s it. The graph is built by walking edges, expanding outward to the depth you ask for.

Trace links are neutral. They do not replace the strong references between records that the modules themselves enforce (for example, a finding pointing at the assessment that produced it). They sit alongside, capturing softer, cross-module relationships and historical context.

Opening the trace graph

From any governed record’s detail page, the trace section provides:

  • a list view (/governance/trace) filtered to that record, showing every direct edge in or out.
  • a graph panel (/governance/trace/graph) showing the same edges as a visual graph, with controls for direction and depth.

The graph controls

  • direction: incoming, outgoing, or both.
  • depth: 1, 2, or 3 hops from the focused record.
  • relationship kind: optional filter to a single edge type.

Depth is capped at 3 to keep the panel readable. For deeper investigation, focus a different node and walk from there.

A worked scenario: a finding that propagates

A regional credit union runs an internal review on its loan-origination workflow. The reviewer creates a finding: “Manual override at 3% above the rate sheet was used 47 times last quarter without supervisor sign-off.”

Opening the trace graph from that finding shows (depth 1, both directions):

  • the assessment that produced it
  • the control whose attestation is invalidated
  • the policy document the control implements
  • the indicator that should have flagged the spike
  • the responsibility assignment for the override review

At depth 2 the panel adds the framework requirement the policy was traced to, the risk the control mitigates, the exception that was opened against the responsibility while the team trains a new supervisor, and the next-quarter assessment plan that will retest it.

The reviewer can compile this picture into an audit packet without opening five separate consoles.

Reading the graph

The panel uses three visual elements:

  • a root node for the record you started from (highlighted).
  • nodes for every other record reached within the depth.
  • edges for every link, drawn from source to target with the relationship kind as a label.

Each node carries enough identifying information (module, resource type, record id) to click through to its detail page. The shape is the same regardless of which module you started from.

When a node appears at multiple depths

The graph collects the shallowest depth at which each node was reached. If a control is reached at depth 1 from a finding and again at depth 3 along a different path, it shows up as depth 1. That’s the canonical answer to “how close is this to my focus point?”

When a record has multiple versions

A node aggregates all version ids seen for a given module/type/id triple within the walk. The graph itself doesn’t choose between versions; it shows you which versions are involved so you can decide if the relationship still applies to the current version.

Most edges are written automatically by the modules themselves when you do governance work (attaching evidence to a control, registering a coverage link, creating an assessment that targets controls). For relationships the modules don’t capture, you can create a link manually.

Requirements:

  • both endpoints must be records the caller can see (RBAC applies).
  • the call must include a reason for change explaining why the link is being recorded.
  • the caller needs the governance.trace:manage permission.

Manual links are audited the same way module-written links are.

When trace is the right tool

Trace fits read-the-room questions:

  • “What touches this?”
  • “If we change this, what cares?”
  • “How did we get from here to there?”

Trace is not the tool for:

  • Enforcing dependencies between records. The owning module’s contracts do that.
  • Authoritative parent-child relationships (an assessment is the parent of its findings; that’s a hard relationship, not a trace edge).
  • Time-ordered activity. For that, use the audit log.
Last updated on
OverviewCatalog lineage