Draft Handling Part 1: Draft Architecture — Active Data and Draft Persistence

📌 KEY POINTS
✅ Draft = a saved, unfinished copy of the data that survives browser refreshes and breaks.
✅ Every instance exists as active (IsActiveEntity = true) and/or draft (IsActiveEntity = false).
✅ Draft data lives in separate draft tables that the framework manages.
⚠️ Your code must use %tky (with %is_draft) — never only the key.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT THIS SERIES COVERS

• Part 1 — draft architecture (this lesson)
• Part 2 — draft lifecycle: create, edit, resume, activate, discard
• Part 3 — draft locking, ETags and concurrency
• Part 4 — validations, determinations and side effects in draft
• Part 5 — troubleshooting draft incidents

Prerequisite: Managed RAP Part 4 (enabling draft).

━━━━━━━━━━━━━━━━━━━━
▶ WHY DRAFT EXISTS
Web apps are stateless: each request is independent. But users edit complex objects over minutes or hours, get interrupted, switch devices. Without draft, unsaved input would be lost and the data could only be checked when the user finally clicks Save. Draft stores every change immediately in a draft copy, so:

• nothing is lost,
• determinations can react while the user types (on modify),
• the object is protected from other editors,
• the active data changes only when the user activates (saves).

━━━━━━━━━━━━━━━━━━━━
▶ TWO VERSIONS OF ONE INSTANCE

• Active instance — the real business data in your persistent tables (zpr_head).
• Draft instance — the work-in-progress copy in the draft table (zpr_head_d).

Both share the same key; they are distinguished by the draft indicator:

• in ABAP/EML: %is_draft = if_abap_behv=>mk-on (draft) or mk-off (active), part of %tky;
• in OData: the key contains IsActiveEntity=true/false.

A new object starts as draft only; an existing object gets a draft when the user clicks Edit.

━━━━━━━━━━━━━━━━━━━━
▶ DRAFT TABLES

• One draft table per entity, generated by ADT from the BDEF quick fix ("draft table zpr_head_d").
• It contains all fields of the entity plus an include with draft administrative fields (the "draft admin include"), e.g. who created the draft and when it was last changed.
• The framework reads and writes draft tables; your code never does.

💡 TIP: after adding a field to the CDS entity, regenerate the draft table — otherwise activation fails with field-mismatch errors.

━━━━━━━━━━━━━━━━━━━━
▶ DRAFT ADMINISTRATIVE DATA
The framework keeps metadata per draft: owner, created at, last changed at, in-process-by user. Fiori uses it to show "Draft", "Locked by …" and "Unsaved changes by …". You do not maintain it yourself.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT THE FRAMEWORK DOES FOR YOU

• Stores every change of a draft instance in the draft tables.
• Handles the draft actions Edit, Activate, Discard, Resume, Prepare.
• Copies draft to active on activation (running the save sequence) and deletes the draft afterwards.
• Manages the exclusive lock on the active instance while a draft exists (Part 3).
• Routes EML and OData requests to draft or active data based on %is_draft / IsActiveEntity.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT YOU DO

• Declare draft in the BDEF (checklist in Behavior Definitions Part 4).
• Use %tky everywhere in handler code.
• Choose on modify vs on save for determinations, and list validations in Prepare (Part 4).

✅ CHECKPOINT: you can explain what happens in the database when a user edits a purchase request with draft.

Users of a non-draft purchase request app lost their input several times a week: long item lists were entered, then a session timeout or accidental browser refresh discarded everything. Validation errors also appeared only at the very end, after twenty minutes of typing.
Enabling draft changed the experience: every field change was stored immediately, users could leave and continue later from any device, calculated totals appeared while typing, and errors surfaced when they clicked Save via Prepare instead of after a failed submit. The number of "lost data" tickets dropped to zero.

• Thinking draft is only a Fiori UI feature — it is a backend persistence concept.
• Writing to or reading from draft tables directly.
• Using key fields instead of %tky, so code works on the wrong version.
• Forgetting to regenerate draft tables after adding fields.
• Enabling draft in API services where clients do not need it.

• Enable draft for UI scenarios with complex or long edits.
• Always use %tky; test every handler with draft and active instances.
• Let the framework manage draft tables and admin data.
• Regenerate draft tables whenever the entity structure changes.
• Keep APIs without draft (separate projection).

Questions: "What is draft in RAP and why is it needed?", "How are draft and active instances distinguished?", "Where is draft data stored?"
Strong answer: draft stores unfinished changes persistently for stateless web apps; each instance can exist as active and draft, distinguished by %is_draft in %tky (IsActiveEntity in OData); draft data lives in framework-managed draft tables with an admin include; activation runs the save sequence, copies draft to active and deletes the draft. Code must use %tky.