Revisions and Versions
Every save of a planning artefact, by a person or by Heimdall, writes a version with its diff, author and reason; read them in the flyout, the API or the tools, and restore any.
By the end of this page you will know what a version is and when one is written, how to read an artefact's versions and see what each changed, who changed it and through what, how to put an earlier version back, and what a client guest, a token and an agent may do with them.
Every change a person or Heimdall makes to a planning artefact writes a version: the record as it was after the save, the columns it changed with their values before and after, who wrote it, through what (the dashboard, a token, an agent, Heimdall) and why (created, edited, moved, restored, drafted, imported). Nothing is ever rewritten: restoring an earlier version writes a new one that names the version it put back, so the history reads forwards and nothing is lost. Epics, work items, requirements, business rules, use cases, RAID items, decisions, glossary terms, data entities, personas and stakeholders carry versions today, a work item's acceptance criteria, a rule's worked examples, a use case's steps, a decision's options and a data entity's fields inside their versions; every artefact joins as it lands.
Before you begin
| You want to | You need |
|---|---|
| Read an artefact's versions | Its view permission (epic:view, work-item:view, requirement:view, business-rule:view, use-case:view, raid:view, decision:view, glossary:view, data-entity:view, persona:view, stakeholder:view) on the project and a staff account. A client guest reads the agreed record, never the drafts behind it. |
| Restore a version | Its update permission (epic:update, work-item:update, requirement:update, business-rule:update, use-case:update, raid:update, decision:update, glossary:update, data-entity:update, persona:update, stakeholder:update). |
When a version is written
A version is written after every save that changes one of the artefact's captured columns: for an epic, the title, the prose, the owner, the priority, the status, the dates and the colour; for a work item, its kind, parent, epic, title, prose, status, resolution, priority, people, estimates, due date, the fields its kind adds and its acceptance criteria rows, so a story and its criteria are kept and restored together; for a requirement, its kind, category, title, statement, rationale, source, priority, measure, verification method, status and owner; for a business rule, its kind, name, statement, condition, action, exceptions, worked examples, authority, priority, the dates in force, status and owner; for a use case, its title, actor, other actors, goal, trigger, conditions, frequency, priority, status and its step rows, so a use case and its flows are kept and restored together; for a RAID item, its kind, title, description, area, probability, impact, mitigation, contingency, owner, dates, dependency and status, the score derived again on every restore; for a decision, its kind, title, context, the options weighed, what was decided, the consequences, status, the day decided, the deciders and the decision it supersedes; for a glossary term, the term, its definition, aliases, related terms, source and status; for a data entity, its component, name, plural, description, owner, PII flag, retention note, status and its fields; for a persona, everything but the picture and the archive flag; for a stakeholder, everything but the linked account. A save that changes none of them (a reorder, a counter) writes nothing, so the history never pads.
| Reason | Written when |
|---|---|
| Created | The artefact is added, by a person, a token or an import. |
| Edited | A person changes the fields by hand, in the editor or through the API. |
| Moved | The artefact moves along its lifecycle, such as draft to in review. |
| Restored | An earlier version is put back. |
| Drafted by Heimdall | Heimdall drafts a change and a person accepts it: an inline draft taken into a field, or a record written through the panel, which names the thread. |
| Imported | The change arrives from a brief import. |
| Approved | An approval carried: the version the approvers read, pinned on the artefact as its approved version. |
| Baselined | A baseline that holds the artefact was frozen: the version is the one pinned, and a requirement or rule moved to baselined with it. |
| Saved as a version | Reserved for the manual-save flow as it lands. |
Each version also records through what it was written: a person in the dashboard, an API token, an MCP client, an integration, a webhook, Heimdall, or the system. The status reference lists every reason.
Read the versions
Open an artefact's detail flyout, on the Epics page for an epic, the Backlog for a work item, the Requirements page for a requirement, the Business Rules page for a rule or the Use Cases page for a use case or the RAID Log page for a RAID item or the Decisions page for a decision, the Glossary or Data dictionary tab for a term or an entity, or the Personas or Stakeholders tab for the people, and scroll to Versions. Newest first, each version shows:
- Its number (
v3), its reason as a badge, and Current on the latest. - One line on what it is: Created, Edited: Goal, Priority, Moved to Approved, Restored version 1.
- Who wrote it and when, with the origin beside the name when it was not a person in the dashboard.
- The columns it changed, each with the value before (struck through) and after.
Show more versions reveals the next five. The Activity button beside it opens the activity history, which records the same saves as a timeline of who did what; the versions are the record itself, the activity is the log around it.
Restore a version
- Find the version to put back and press Restore this version; the current version has no button, because it is already in place.
- Confirm. The record as it stands is kept as a version too, so nothing is lost.
The version's captured columns, the status included, are written back onto the artefact and a new
version is written with the reason restored, naming the one put back. The flyout reloads with
the restored record and epic.restored, work_item.restored, requirement.restored, business_rule.restored, use_case.restored, raid_item.restored, decision.restored, glossary_term.restored, data_entity.restored, persona.version_restored or stakeholder.restored goes out with both version numbers. A version identical
to the current record is refused, since there is nothing to restore.
Approved and baselined artefacts
A restore puts the version's status back with its fields, so an approved artefact restored to a draft version reads as a draft again and needs a new approval before a client guest sees it; the approval it had stays in its history. A restore that keeps the status marks the artefact changed since its approval, and the approval bar asks for a new submission. An artefact a frozen baseline holds cannot be restored at all: the restore is refused with the baseline named, until an approved change request unlocks the artefact.
What a guest, a token and an agent see
- A client guest never reads versions: they read the agreed record, and the versions are the drafts and the arguments behind it. The flyout shows them no Versions section.
- A token reads an epic's versions through
GET /v1/epics/{epic}/revisionsand one version throughGET …/revisions/{revision}, underepic:view, and restores one throughPOST …/revisions/{revision}/restoreunderepic:update; a work item's through the same three verbs under/v1/work-items/{item}, withwork-item:viewandwork-item:update; a requirement's under/v1/requirements/{requirement}, withrequirement:viewandrequirement:update; a rule's under/v1/business-rules/{rule}, withbusiness-rule:viewandbusiness-rule:update; a use case's under/v1/use-cases/{useCase}, withuse-case:viewanduse-case:update; a RAID item's under/v1/raid-items/{raidItem}, withraid:viewandraid:update; a decision's under/v1/decisions/{decision}, withdecision:viewanddecision:update; a term's under/v1/glossary/{term}, an entity's under/v1/data-entities/{entity}, a persona's under/v1/personas/{persona}and a stakeholder's under/v1/stakeholders/{stakeholder}, each with its own view and update abilities. - An agent reads versions with
list_revisionsandget_revisionand restores one withrestore_revision, which is destructive in the MCP sense and asks the client for confirmation. The tools needactivity:readand the artefact's own ability, and refuse a guest token.
What happens next
- A restore is announced as
epic.restored,work_item.restored,requirement.restored,business_rule.restored,use_case.restored,raid_item.restored,decision.restored,glossary_term.restored,data_entity.restored,persona.version_restored(persona.restoredis the archive flag lifted) orstakeholder.restoredwith the version put back and the version written, so a mirror re-reads the record rather than guessing what moved. - An approval binds its request to the version under review and, when it carries, writes a version with the reason approval and pins it on the artefact as the approved version; a baseline freezes a set of those approved versions on the same foundation and locks the artefacts it holds until a change request unlocks them.
Heimdall on this page
Heimdall reads versions through list_revisions and get_revision. A restore it proposes is
shown first and waits for your go-ahead, like every change it makes.
From the API and MCP
Epics API
The versions endpoints under each epic: list, read and restore.
Work Items API
The same three verbs under each work item, criteria included.
Requirements API
The same three verbs under each requirement.
Business Rules API
The same three verbs under each rule, examples included.
Use Cases API
The same three verbs under each use case, steps included.
RAID Log API
The same three verbs under each RAID item.
Decisions API
The same three verbs under each decision, options included.
Glossary API
The same three verbs under each term.
Data Entities API
The same three verbs under each entity, fields included.
Personas API
The same three verbs under each persona.
Stakeholders API
The same three verbs under each stakeholder.
Planning tools
list_revisions, get_revision and restore_revision.
Permissions
| Action | Permission |
|---|---|
| Read versions | The artefact's view permission (epic:view, work-item:view, requirement:view, business-rule:view, use-case:view, raid:view, decision:view, glossary:view, data-entity:view, persona:view, stakeholder:view), staff only |
| Restore a version | The artefact's update permission (epic:update, work-item:update, requirement:update, business-rule:update, use-case:update, raid:update, decision:update, glossary:update, data-entity:update, persona:update, stakeholder:update) |
Frequently asked
Related
- Epics — the first artefact that carries versions
- Backlog — work items, versioned with their acceptance criteria
- Functional requirements — requirements, versioned with their kind, category and measure
- Business rules — rules, versioned with their worked examples
- Use cases — use cases, versioned with their steps
- RAID log — risks, assumptions, issues and dependencies, their score derived again on every restore
- Decisions — decisions, versioned with their options
- Glossary — terms, versioned with their aliases and related terms
- Data dictionary — entities, versioned with their fields
- Personas — personas, versioned without their picture or archive flag
- Stakeholders — stakeholders, versioned without their linked account
- Activity log — the timeline around the versions
- Status reference — every revision reason and actor kind
How is this guide?
Last updated on
Attachments
The Files panel in every artefact flyout: pin wireframes, signed specifications and sample files on epics, stories, requirements, rules, use cases, RAID items, decisions and dictionary entries, read them through the application, and remove them.
Approvals
Submit an epic, story, requirement, rule or use case for review, who decides under the project's policy, the inbox, resubmitting after changes, withdrawing, the clocks, and what a client guest signs.