Drafts

Use a draft when you want to try a change — a planning scenario, a retirement, a target landscape — without changing what everyone else sees. You edit as usual. Those edits stay off the current live workspace until you publish.

Snapshots are a different tool: they let you browse the workspace as it was on a past date. They never include draft work.

A workspace admin can show the drafts chip in the top-right navigation under Settings > Feature flags. The flag only controls that chip; drafts still work from /drafts.

How a draft relates to the live workspace

A draft is not a copy of the workspace. It is an overlay: it stores only the objects you create, edit, or delete. Everything else is the live workspace.

While the draft is open you always see the live workspace plus this overlay.

If a teammate updates an item on the live workspace that this draft has not touched, that update is visible in the draft immediately. If this draft already changed that same item, the overlay wins until you publish or resolve a Conflict.

Diagrams and BPMN you actually edit keep a draft canvas until you publish. Unedited diagrams keep tracking the live workspace.

If you know Git

Caplo drafts are not Git branches.

A Git branch forks at a point in time. Later commits on main stay off the branch until you rebase or merge.

A Caplo draft never forks. It keeps tracking the live workspace and only records the objects you changed. Publish is closer to applying a patch than merging a branch: the whole overlay lands on live, or nothing does.

	Git branch	Caplo draft
What is stored	A copy of the whole tree	Only the objects you changed
Later live edits	Hidden until rebase or merge	Visible unless this draft changed the same object
Combining work	Rebase or merge	Publish
Conflicts	Same lines in a file	Same object changed on both sides

Create and switch drafts

Create a draft from the header drafts menu (New draft) or from the Drafts page (+). Give it a name, an optional description, and choose Personal or Shared. New drafts default to Shared.

Open an existing draft from the list, or use the edit icon to start working in it without opening the review page. Each row shows how much changed, who created it, and a reviewer when one is assigned.

You can rename an open draft, change its description, or switch it between Personal and Shared. Published drafts stay as a record and cannot be edited.

Use View to start working in a draft. The header chip shows which draft is active. From there you can open the draft’s page, pick another draft, return to the current workspace, or create a new one. Switching to another Caplo workspace also leaves the draft and shows that workspace’s current live version.

Work in a draft

While a draft is active you can create, edit, and delete the same overlay objects you would on the live workspace: entities, relations, diagrams, BPMN, reports, views, and folders. Those writes stay in the overlay. Property definitions stay live workspace settings — editing them while a draft is open still updates the current workspace. Creating an entity with the same name and type as one deleted on the live workspace asks whether to restore it, just as it does outside a draft.

Overview shows a Draft strip under the workspace name so you know the tree is that overlay, not the live workspace alone. Exit takes you back to the live workspace. Page breadcrumbs also show a Draft chip — for example Reports › Application Landscape then Draft “Q2 planning”. Click it to open the draft’s page.

Items you create only in the draft appear in Overview while the draft is active. Items you change show an overlay icon next to their name.

History on an item includes the live versions and the versions on this draft. Restore writes the draft, not the live workspace. Restoring the live version drops that item from the draft’s change list. If you delete an entity or relation in the draft, it stays on diagrams with a warning until you restore it.

Personal or Shared

• Personal — only you see the draft. Use this to try something on your own.
• Shared — the workspace can see it. Use this when someone else should review or continue the work. You can assign a reviewer on Shared drafts.

Shared drafts can only change Shared (workspace) items. You can still promote a Personal diagram, report, view, or folder to Shared while you work. Overview grays out Personal and labels it Not part of this shared draft. Save dialogs lock Team to Shared with the same reason.

To share a Personal draft, move or remove every Personal change first. Making a Shared draft Personal is always allowed. Workspace admins can also list and publish Personal drafts.

Review and discuss

The draft page is where you review the scenario before it goes live.

• Conversation — why this draft exists, who is reviewing it, comments, and publish
• Changes — every object this draft would add, update, or remove
• Conflicts — every object that blocks publish. The number next to the tab matches this list

On Conversation you can read the description, see how much changed, assign a reviewer (Shared drafts), and follow the timeline of edits and comments. Anyone who can see the draft can comment. You can attach a comment to a changed object.

On Changes you can inspect each object, open it on its full page, and restore a version onto the draft. Entities and relations show the same detail you use in Repository, plus a Change summary. Diagrams, BPMN, and reports show a preview of what the draft looks like.

Resolve conflicts and publish

Publish writes the whole draft onto the live workspace, or nothing. Draft-only objects stay off the live workspace until that moment — they never appear as unpublished rows in the live repository. If someone changed the live workspace under one of your edits, or a name or relation already exists there, Caplo lists those objects on Conflicts. A diagram that still shows an entity or relation this draft deleted is valid — those shapes stay with a warning, the same as outside a draft.

For each conflict you choose:

• Keep this version under Draft — keep your scenario. Publish later writes it onto the live workspace
• Keep this version under Current live version — drop that draft change

You can also edit the draft and try again. Resolving a conflict does not publish.

Use Publish at the bottom of Conversation when there are no conflicts and every comment thread is resolved. After publish, each changed object gets one History row, and Dashboard Latest actions shows {draft name} was published. Draft versions stay on the draft and do not appear in snapshots.

Delete an unpublished draft to throw the scenario away. Published drafts stay as the publish record.

Diagrams and BPMN you edit in a draft keep their own copy until you publish. Publish copies that drawing onto the live diagram and adds a Published row in History so you can view or restore it.

REST and MCP

You can create and update drafts, and edit entities, relations, and BPMN inside a draft, from the public API or MCP. REST mutations must send exactly one write target (Caplo-Write-Target: main or Caplo-Draft-Id). MCP mutation tools already require draftId. Publish and delete stay in the Caplo UI.

Turning the Drafts flag off hides the top-nav drafts chip on the live workspace. Existing drafts stay editable from /drafts. Workspace copy copies only live data and asks you to confirm discarding drafts first.

See History and snapshots, MCP connections, and the Public REST API.