Lesson 1 of 5
Draft
10 min
Listen to this lesson
Contoso Motor Co.'s fleet customers pay a deposit on every alternator and get it back when they return the old unit. Those core return agreements live in custom tables that the system conversion carried over from ECC. Kenji's team is replacing the old maintenance transaction with a Fiori elements app built on a managed RAP business object, ZR_CMC_CoreAgreement, with a root entity for the agreement and a child entity for its items. Maria's team edits agreements that run to dozens of items and are often interrupted by phone calls. They need to save half-finished work without it becoming live. That is what draft is for.
What draft gives you
With draft, every change a user makes is stored in a separate draft table, not in the active tables. The user can leave and come back later, from another device, and continue. Validations can run as the user goes, and nothing becomes active until the user saves, which in draft terms means activating the draft. Other users keep seeing the active version until then. For Fiori elements object pages, draft is the normal editing model.
Enabling draft in the behavior definition
Draft is switched on for the whole business object with with draft; in the behavior definition header; SAP's documentation notes it cannot be enabled for individual entities. Each entity then needs a draft table, which the RAP framework fills and empties; you never write to it yourself. The root needs a total etag field in addition to its lock master, and associations within the BO must be draft-enabled so that navigating from a draft root reaches draft items and from an active root reaches active items.
| Element | Purpose | Contoso example |
|---|---|---|
| with draft | Enables draft for the whole BO | In the header of ZR_CMC_CoreAgreement |
| draft table | Stores draft instances per entity | ZCMC_CORE_AGR_D for the root, ZCMC_CORE_AGI_D for items |
| lock master | Root entity controls locking for the BO | Agreement root; items are lock dependent |
| total etag | Detects changes to the active instance while a draft exists | LastChangedAt, filled by the framework |
| draft actions | Edit, Activate, Discard, Resume, and the determine action Prepare | Declared explicitly; Activate optimized |
The building blocks of a draft-enabled managed BO.
The draft lifecycle
- EditCopies the active agreement into the draft table and locks the active instance exclusively
- ChangeEach field change updates the draft; determinations and validations can run on modify
- Lock expiresAfter a configurable time, the exclusive lock ends and the optimistic phase begins
- ResumeModifying a draft whose lock expired re-establishes the lock, if the total ETag shows the active version is unchanged
- PrepareRuns the on-save determinations and validations assigned to it
- Activate or DiscardActivate writes the draft to the active tables and clears it; Discard deletes the draft
The total ETag is what makes the optimistic phase safe. When Maria starts editing agreement 100045 for Great Lakes Fleet Services, the active instance is locked. If she leaves it overnight, the exclusive lock expires. If nobody touched the active agreement in the meantime, her draft's total ETag still matches and she can resume. If Dan's team changed the active agreement through another channel, the ETags differ and her draft cannot be resumed; she must discard it and start again from the current version.
Draft in code
In handler methods and EML, the key of a draft-enabled entity includes the draft indicator %is_draft. SAP's cheat sheets recommend working with the transactional key %tky, which contains %is_draft, rather than %key, so the same code handles draft and active instances correctly. A classic bug is reading with %key inside a determination and getting the active instance when the user is editing a draft.
- Is a second user editing the same agreement?Yes → the exclusive lock stops them with a message · No → continue
- Has the exclusive lock expired?Yes → Resume on next change, if total ETags match · No → keep editing
- Did someone change the active instance meanwhile?Yes → the draft cannot be resumed; discard and re-edit · No → resume works
- Does Prepare report errors at activation?Yes → the draft stays, with messages to fix · No → active data is written
What would you do?
In testing, Maria edits an agreement, goes to lunch, and comes back to an error saying her changes cannot be continued. Meanwhile an interface had updated the same agreement's active version. What is the right analysis?
- Draft stores in-progress changes separately; activation makes them live.
- with draft applies to the whole BO; each entity needs a draft table; the root needs a total etag.
- Draft actions: Edit, Activate (runs Prepare), Discard, Resume, and the determine action Prepare.
- Use %tky, which includes %is_draft, so code handles draft and active instances correctly.
Check your understanding · not graded
Lesson check
1. At what scope is draft enabled for a RAP business object?
2. What does the draft action Prepare do?
3. Why is a total etag required in a draft-enabled BO?
4. Which key component should handler code use so it works for draft and active instances?