Draft: the UX users expect
Modern Fiori apps let users start editing, walk away, and come back — nothing goes live until they explicitly save. In CAP, this is draft handling, enabled with a single annotation.
One annotation —
@odata.draft.enabled— and CAP generates draft tables, edit/activate/discard actions, and the whole draft lifecycle.
Enabling draft
service OrderService {
@odata.draft.enabled
entity Orders as projection on my.Orders;
}That's the entire setup. CAP creates shadow draft tables, adds the draftAdministrativeData fields, and exposes the standard draft actions (draftEdit, draftActivate, draftDiscard) on the OData endpoint.
What the framework does for you
- Draft tables — parallel tables hold in-progress edits; active data stays untouched.
- Edit/activate/discard — standard actions with optimistic locking via ETags.
- Draft admin data — who created the draft, when, and whether it's in process.
- Fiori integration — Fiori Elements renders the draft indicator, edit/save/discard buttons automatically.
Validations and drafts: the key insight
Drafts tolerate inconsistency — that's the point. Run strict validations at activation, not on every keystroke:
this.before('SAVE', 'Orders', async (req) => {
// SAVE fires on draft activation
if (!req.data.customer_ID) {
req.error(400, 'Customer is required before activation');
}
});The SAVE event fires when the draft is activated. Users can keep half-filled drafts; they just can't activate invalid data.
Validate on SAVE (activation), not on CREATE/UPDATE (draft edits). Blocking draft saves destroys the draft UX.
Draft gotchas
- Compositions need draft too — child entities in a composition must also be draft-enabled for the object page to work.
- Don't maintain admin fields — read
DraftAdministrativeData, never write it. - ETags matter — concurrent edits are resolved through them; custom update logic must respect ETag handling.
- Side effects — trigger follow-up logic (notifications, recalculations) on SAVE, not on draft edits.
When not to use draft
Draft isn't free — it doubles your tables and adds lifecycle complexity. Skip it for entities users never edit interactively: reference data, logs, and entities managed by background jobs.
Also think twice for simple single-field edits. Draft shines for multi-field, multi-section object pages where users genuinely work incrementally. A one-field toggle doesn't need a draft lifecycle.
The heuristic: if the edit fits in one row of a table and saves instantly, draft is overhead. If it's a form users fill over minutes, draft is essential.
Draft is a feature, not a burden
Users consider draft behavior table stakes in 2026. With CAP it's nearly free — enable the annotation, put validations on SAVE, and let the framework do the rest.
Draft activation errors? Share the message in the comments.