RAP Build-Along Part 3: Behavior Definition — Managed, Draft, Locking and ETags

📌 KEY POINTS
✅ Managed BDEF header: implementation class, strict ( 2 ), with draft.
✅ Root: lock master, total etag, etag master, authorization master.
✅ Declare field control (readonly, mandatory) and numbering (managed UUID).
⚠️ Draft needs draft tables and draft actions (Edit, Activate, Discard, Resume, Prepare).

▶ SAP RAP BEHAVIOR DEFINITION: MANAGED RAP, DRAFT, LOCKING AND ETAGS (PART 3)

━━━━━━━━━━━━━━━━━━━━
▶ WHAT YOU WILL BUILD

The behavior definition (BDEF) ZI_RAP_Travel, the generated draft tables ZRAP_TRAV_D and ZRAP_BOOK_D, and an (initially empty) behavior pool ZBP_I_RAP_TRAVEL. After this part the BO can be created, changed, and deleted through EML, with drafts, locks and optimistic concurrency handled by the managed framework. Custom logic (determinations, validations, actions) is only *declared* here; Part 4 implements it.

━━━━━━━━━━━━━━━━━━━━
▶ PREREQUISITES / PREVIOUS PART

• [Part 2](/lessons/rap-bootcamp-part-2-persistence-cds) completed: active tables ZRAP_TRAVEL, ZRAP_BOOKING; root ZI_RAP_Travel with composition to ZI_RAP_Booking.
• Your release supports strict mode and draft for managed BOs. strict ( 2 ) is available in current SAP BTP ABAP environment and recent S/4HANA releases; older releases may only support strict or no strict mode (release-dependent).

━━━━━━━━━━━━━━━━━━━━
▶ WHY A BEHAVIOR DEFINITION EXISTS

CDS describes *data*. The BDEF describes *what may happen to it*: which operations exist, who owns locks, how concurrency is detected, where data is saved, and which custom rules run. In a managed scenario, the framework implements the standard operations (create, update, delete, read, lock, draft handling, save) from this declaration. You write ABAP only for behavior that is genuinely business-specific.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 1 — CREATE THE BDEF

Right-click ZI_RAP_Travel → *New Behavior Definition*, implementation type Managed. ADT generates a skeleton for the root and every composed child. Replace it with the full BDEF in the code section. Walk through it block by block.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 2 — HEADER: MANAGED, STRICT, DRAFT, IMPLEMENTATION CLASS

┏━━ CODE ━━━━━━━━━━━━
┃ managed implementation in class zbp_i_rap_travel unique;
┃ strict ( 2 );
┃ with draft;
┗━━━━━━━━━━━━━━━━━━━

• managed — framework handles standard operations and save.
• implementation in class ... unique — one behavior pool for the BO; each entity gets its own local handler class inside it.
• strict ( 2 ) — enforces current best-practice rules (for example, explicit authorization, no deprecated syntax). It reports issues that would otherwise surface at runtime.
• with draft — draft-enables the whole BO. All composed children become draft-enabled with it.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 3 — PERSISTENCE AND DRAFT TABLE MAPPING

┏━━ CODE ━━━━━━━━━━━━
┃ persistent table zrap_travel
┃ draft table zrap_trav_d
┗━━━━━━━━━━━━━━━━━━━

The persistent table is where active data is saved. The draft table holds edit-in-progress data. Put the cursor on zrap_trav_d, press Ctrl+1, choose *Create draft table*, and activate. Do the same for zrap_book_d. The generated table uses CDS alias names and includes "%admin" : include sych_bdl_draft_admin_inc.

Because CDS aliases (TravelUUID) differ from DB field names (travel_uuid), add a mapping for block per entity. Without mapping, the managed save cannot move fields between CDS and DB. In newer releases mapping for zrap_travel corresponding plus exceptions is supported; the explicit list below works on all releases that support draft (release-dependent syntax).

━━━━━━━━━━━━━━━━━━━━
▶ STEP 4 — LOCKING: LOCK MASTER AND LOCK DEPENDENT

• Root: lock master total etag LastChangedAt — the root owns the lock. Editing any Booking locks the whole Travel.
• Child: lock dependent by _Travel — the child borrows its parent's lock through the parent association.

With draft, an *exclusive draft* is taken when a user presses Edit; the enqueue lock on the active instance is held for the draft's lifetime until activation or discard. A second user sees "locked by user X".

━━━━━━━━━━━━━━━━━━━━
▶ STEP 5 — AUTHORIZATION: MASTER AND DEPENDENT

• Root: authorization master ( instance, global ) — you will implement instance and global authorization methods in Part 4.
• Child: authorization dependent by _Travel — the Booking follows its Travel's authorization.

strict ( 2 ) requires this declaration. DCL (@AccessControl.authorizationCheck: #CHECK plus an access-control object) restricts reading. It does not authorize create, update, delete or actions. Modification authorization is always RAP behavior authorization.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 6 — ETAG: LOCAL AND TOTAL

| ETag | Declared on | Field | Purpose |
|---|---|---|---|
| Total ETag | Root, with draft | LastChangedAt | Detects changes to the active instance while a draft exists; checked when the draft is resumed/activated |
| Local ETag | Each entity | LocalLastChangedAt | Optimistic concurrency per instance for OData requests (If-Match) |

Root: etag master LocalLastChangedAt. Child: etag master LocalLastChangedAt as well (each Booking row has its own local timestamp from Part 2). Alternatively, a child can use etag dependent by _Travel. Because the @Semantics annotations from Part 2 are present, the managed framework updates these timestamps on every save.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 7 — NUMBERING: UUID VS SEMANTIC

┏━━ CODE ━━━━━━━━━━━━
┃ field ( numbering : managed, readonly ) TravelUUID;
┗━━━━━━━━━━━━━━━━━━━

Managed numbering means the framework generates a UUID on create. Consumers never supply a key.

| Strategy | Declaration | When |
|---|---|---|
| Managed UUID | numbering : managed on UUID key | Default for new managed BOs |
| Early numbering | early numbering + earlynumbering_create handler | Semantic key needed at create time |
| Late numbering | late numbering + adjust_numbers in saver | Gap-free numbers assigned at save |

The readable TravelID is not the key, so we fill it in a determination (Part 4) — simple and clean. For gap-free legal numbers, late numbering with a number range is the right pattern.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 8 — FIELD CONTROL

┏━━ CODE ━━━━━━━━━━━━
┃ field ( readonly ) TravelID, TotalPrice, OverallStatus, CreatedBy, CreatedAt,
┃ LastChangedBy, LastChangedAt, LocalLastChangedAt;
┃ field ( mandatory ) CustomerID, BeginDate, EndDate, CurrencyCode;
┃ field ( readonly : update ) AgencyID;
┃ field ( features : instance ) BookingFee;
┗━━━━━━━━━━━━━━━━━━━

• readonly — computed or framework-owned.
• mandatory — UI marks as required; it does not replace a validation (Part 4 still validates dates).
• readonly : update — may be set on create, not afterwards.
• features : instance — dynamic: decided per instance in Part 4 (for example, BookingFee read-only once accepted).

━━━━━━━━━━━━━━━━━━━━
▶ STEP 9 — OPERATIONS, ASSOCIATIONS, AND CUSTOM BEHAVIOR DECLARATIONS

Root: create; update; delete; association _Booking { create; with draft; }. The with draft on the association lets bookings be created inside an open Travel draft.

Child: update; delete; association _Travel { with draft; }. No standalone create — Bookings are created only through their parent (create-by-association).

Declared custom behavior (implemented in Part 4):

• Determinations: setInitialStatus on modify { create; }, calculateTravelID on save { create; }, recalcTotalPrice on modify { field BookingFee, CurrencyCode; }, on child calcTotalOnBooking on modify { field FlightPrice, CurrencyCode; create; }.
• Validations: validateDates on save { create; field BeginDate, EndDate; }, validateCustomer, on child validateFlightPrice.
• Actions: action ( features : instance ) acceptTravel result [1] $self; and rejectTravel.
• determine action Prepare { validation validateDates; validation validateCustomer; validation Booking~validateFlightPrice; }.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 10 — DRAFT ACTIONS AND THE DRAFT LIFECYCLE

┏━━ CODE ━━━━━━━━━━━━
┃ draft action Edit;
┃ draft action Activate optimized;
┃ draft action Discard;
┃ draft action Resume;
┃ draft determine action Prepare;
┗━━━━━━━━━━━━━━━━━━━

Lifecycle:

┏━━ CODE ━━━━━━━━━━━━
┃ Active ──Edit──> Draft (exclusive, locked) ──Prepare──> validated
┃ ^ │ └─Discard──> (draft deleted, lock released)
┃ └────Activate───────┘ (Prepare runs, then draft → active, save sequence)
┃ Resume: re-acquire lock for an expired/closed draft session
┗━━━━━━━━━━━━━━━━━━━

Activate optimized (release-dependent, newer releases) reduces redundant determination runs. On older releases use draft action Activate;. Validations run on Prepare and on Activate; draft data may be *invalid* while the user edits — that is intended.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 11 — CREATE THE BEHAVIOR POOL

Put the cursor on zbp_i_rap_travel → Ctrl+1 → *Create behavior implementation class*. ADT generates local handler classes lhc_Travel and lhc_Booking with method stubs for every declared determination, validation, action, feature and authorization method. Activate with empty methods; the BO now works for plain CRUD.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 12 — SMOKE TEST WITH EML

Run the small classrun in the code section. It creates a Travel with one Booking via create-by-association and commits. Part 6 builds full tests; this proves the BDEF, mapping and draft tables are consistent.

━━━━━━━━━━━━━━━━━━━━
▶ CHECKPOINT

• [ ] BDEF active with managed, strict ( 2 ) (or your release's level), with draft.
• [ ] Draft tables ZRAP_TRAV_D / ZRAP_BOOK_D generated and active.
• [ ] Mapping blocks present for both entities.
• [ ] Root is lock and authorization master; child is dependent.
• [ ] Total ETag LastChangedAt, local ETag LocalLastChangedAt.
• [ ] TravelUUID/BookingUUID use managed numbering.
• [ ] Behavior pool ZBP_I_RAP_TRAVEL generated and active.
• [ ] Smoke test creates Travel + Booking and they appear in Data Preview.

━━━━━━━━━━━━━━━━━━━━
▶ TRY IT YOURSELF

Add a cancelBooking action on the Booking entity with result [1] $self, add it to the child handler stub, and reactivate. Then decide whether it should be features : instance (hint: a cancelled booking cannot be cancelled again).

━━━━━━━━━━━━━━━━━━━━
▶ INTERVIEW TAKEAWAY

"A managed BDEF declares the transactional contract: persistent and draft tables with field mapping, the root as lock and authorization master with children dependent, a total ETag for draft plus local ETags per instance, managed UUID numbering, static and instance field control, create-by-association for children, and the draft actions Edit, Activate, Discard, Resume and Prepare. The framework implements all of that; my behavior pool only contains business rules."

━━━━━━━━━━━━━━━━━━━━
▶ NEXT PART

[Part 4: Determinations, Validations, Actions, Messages and Authorization](/lessons/rap-bootcamp-part-4-behavior-implementation) implements the declared rules.

A support team received tickets that two dispatchers could edit the same travel's bookings simultaneously in a custom app, with the last save silently winning. The BO had declared the child as its own lock master and had no local ETag. Changing the child to lock dependent by _Travel, adding etag master LocalLastChangedAt with the managed timestamp annotation, and relying on the root's total etag for drafts turned silent overwrites into a clear "locked by user" or "data changed" message.

• Forgetting the mapping for block when CDS aliases differ from DB fields — saves write nothing or fail.
• Hand-writing the draft table instead of generating it; any alias drift breaks activation.
• Declaring create on the child instead of creating only by association.
• Treating field ( mandatory ) as a validation — it is a UI/consumer hint; validate on save anyway.
• Omitting total etag in a draft BO; draft resume cannot detect concurrent active changes.
• Believing DCL covers create/update/delete; modification needs authorization master.
• Using Activate optimized on a release that does not support it — check ADT syntax help.

• Enable the strictest strict mode your release supports.
• Root owns lock, authorization and total ETag; children are dependent.
• Use managed UUID numbering; fill readable IDs in a determination or late numbering.
• Keep static field control in the BDEF, dynamic control in features : instance.
• Generate draft tables and behavior pool from quick fixes.
• Declare every validation that must run before activation in Prepare.
• Smoke-test with EML before building any UI.

Typical questions: "Difference between lock master and lock dependent?" "What are total and local ETag used for in draft?" "Managed vs early vs late numbering?" "What does with draft on an association do?" Answer with the lifecycle: Edit acquires exclusive draft and lock; Prepare runs validations; Activate copies draft to active through the save sequence; Discard releases the lock.