RAP Build-Along Part 2: Persistence Tables, Root and Child CDS Views

📌 KEY POINTS
✅ Persistence tables need client, UUID key, business fields and admin fields.
✅ Root view: "define root view entity"; child: "association to parent".
✅ Composition from root to child; parent key in the child.
⚠️ Annotate admin fields (@Semantics) so managed RAP maintains them.

▶ SAP RAP CDS TUTORIAL: PERSISTENCE TABLES, ROOT AND CHILD CDS VIEWS (PART 2)

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

By the end of this part, your package contains:

| Artifact | Name | Purpose |
|---|---|---|
| Active table (root) | ZRAP_TRAVEL | Persisted Travel rows |
| Active table (child) | ZRAP_BOOKING | Persisted Booking rows |
| Draft table (root) | ZRAP_TRAV_D | Draft Travel rows (generated in Part 3) |
| Draft table (child) | ZRAP_BOOK_D | Draft Booking rows (generated in Part 3) |
| Root CDS view entity | ZI_RAP_Travel | Business-object root of the data model |
| Child CDS view entity | ZI_RAP_Booking | Composed child with parent association |

No behavior yet. The goal is a data model that previews correctly in the ADT Data Preview and is ready to carry a managed behavior definition in Part 3.

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

• Completed [Part 1](/lessons/rap-basics-architecture-cds-behavior-service): you understand the artifact chain and have a transportable package (for example ZRAP_TRAVEL_APP) with a transport request.
• ADT (Eclipse) connected to an ABAP system that supports RAP managed scenarios with draft. SAP BTP ABAP environment, SAP S/4HANA Cloud Public Edition developer extensibility, or a recent SAP S/4HANA (on-premise/private) release all work, but available syntax differs by release — this lesson labels those spots.
• Authorization to create dictionary objects and CDS in your package.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 1 — DECIDE THE DATA MODEL BEFORE TYPING

A RAP business object is a tree. Here the tree is:

┏━━ CODE ━━━━━━━━━━━━
┃ Travel (root) ZRAP_TRAVEL -> ZI_RAP_Travel
┃ └── Booking (child) ZRAP_BOOKING -> ZI_RAP_Booking
┗━━━━━━━━━━━━━━━━━━━

Decisions made now are expensive to change later:

1. Technical key: a 16-byte UUID (sysuuid_x16) for both entities. UUIDs let the managed framework assign keys at create time without number-range objects and make draft handling simple.
2. Business ID: a readable travel_id (for example 00000042) shown to users. It is *not* the key; Part 3 and Part 4 show how to fill it.
3. Parent foreign key: ZRAP_BOOKING-parent_uuid stores the Travel UUID. The child's own key is booking_uuid.
4. Admin fields: created by/at, last changed by/at, and a *local* last-changed timestamp. These feed ETag and audit in Part 3.
5. Amounts: every amount has a currency field next to it.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 2 — CREATE THE ACTIVE TABLES IN ADT

Order: root table first, then child table, because the child's structure refers to the parent's key conceptually (no DDIC foreign key is required for RAP).

In ADT: right-click the package → *New* → *Other ABAP Repository Object* → *Dictionary* → *Database Table*. Name ZRAP_TRAVEL, description "RAP Bootcamp Travel". Replace the template with the definition in the code section and activate. Repeat for ZRAP_BOOKING.

Notes on the definitions:

• client : abap.clnt is the first key field in on-premise and private cloud systems. In ABAP Cloud, client handling is still present in tables you create.
• @AbapCatalog.deliveryClass : #A marks application data.
• @Semantics.amount.currencyCode on the amount field links the amount to its currency field. Without it, activation reports an error for abap.curr fields.
• local_last_changed_at changes on *every* save of that row; last_changed_at is the total (root-level) timestamp. Part 3 uses them for local and total ETag.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 3 — PLAN THE DRAFT TABLES (DO NOT HAND-WRITE THEM YET)

Draft-enabled RAP BOs need one draft table per entity. The draft table mirrors the CDS entity's field names (not the DB table's) and adds the technical include sych_bdl_draft_admin_inc ("%admin"). The easiest correct path is to let ADT generate it:

1. Write the behavior definition in Part 3 with with draft; and draft table zrap_trav_d.
2. Place the cursor on the unknown table name and use the quick fix "Create draft table".

Doing it that way guarantees field names and types match the CDS aliases. If you hand-write the draft table now and later rename a CDS alias, activation of the BDEF fails with a field-mismatch error. We reserve the names ZRAP_TRAV_D and ZRAP_BOOK_D now so the whole series is consistent.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 4 — CREATE THE ROOT CDS VIEW ENTITY

Right-click the package → *New* → *Data Definition*. Name ZI_RAP_Travel, referenced object ZRAP_TRAVEL, template *Define Root View Entity*.

Key points:

• define root view entity marks this as the root of the BO. Only one root per BO.
• Aliases in CamelCase (TravelUUID, TravelID) become the RAP field names used in BDL, EML and the UI. Choose them carefully; they flow through every later part.
• composition [0..*] of ZI_RAP_Booking as _Booking declares ownership: bookings live and die with their Travel. A composition cannot activate until the target entity exists and declares the matching parent association — see the activation sequence below.
• @Semantics.user.createdBy, @Semantics.systemDateTime.createdAt, ...localInstanceLastChangedAt, ...lastChangedAt tell the managed framework which fields it should fill automatically. With these annotations you write no code for admin fields.
• @Semantics.amount.currencyCode: 'CurrencyCode' on TotalPrice (release-dependent: in older releases the reference was set through the underlying table only; in current releases the CDS annotation is expected for view entities).

━━━━━━━━━━━━━━━━━━━━
▶ STEP 5 — CREATE THE CHILD CDS VIEW ENTITY

New *Data Definition* ZI_RAP_Booking, referenced object ZRAP_BOOKING, template *Define View Entity*.

• association to parent ZI_RAP_Travel as _Travel on $projection.ParentUUID = _Travel.TravelUUID — the ON condition joins the child's foreign key to the parent's key. It must use $projection fields (the aliased names).
• The child is not a root, so it uses define view entity, not define root view entity.
• Keep the same semantic annotations for amounts and the local ETag field.

━━━━━━━━━━━━━━━━━━━━
▶ CARDINALITY AND ON CONDITIONS

| Declaration | Where | Meaning |
|---|---|---|
| composition [0..*] of ZI_RAP_Booking as _Booking | Root | A Travel owns zero or more Bookings |
| association to parent ZI_RAP_Travel as _Travel on ... | Child | Each Booking has exactly one parent; cardinality is implicit [1..1] |
| association [0..1] to I_Currency as _Currency | Either | Optional lookup association (released API) — *not* part of the BO tree |

Compositions define the BO structure and drive create-by-association, cascade delete, and lock/ETag inheritance. Plain associations are only navigation. Do not model the parent relationship as a normal association: the BDEF in Part 3 will reject it.

━━━━━━━━━━━━━━━━━━━━
▶ STEP 6 — ACTIVATION SEQUENCE (THE PART THAT TRIPS EVERYONE)

The root references the child through the composition, and the child references the root through the parent association. Neither activates alone. Use one of these approaches:

1. Mass activation (recommended): create both data definitions (they can be inactive), then press *Activate All* (Ctrl+Shift+F3) and select both. ADT resolves the cycle.
2. Two-pass: activate ZI_RAP_Travel without the composition line, activate ZI_RAP_Booking with its parent association, then add the composition back to the root and activate again.

Full order for this part:

1. ZRAP_TRAVEL (table) → activate
2. ZRAP_BOOKING (table) → activate
3. ZI_RAP_Travel + ZI_RAP_Booking → mass-activate together
4. Optional: run the data generator class from the code section to insert test rows
5. Data Preview (F8) on ZI_RAP_Travel → follow _Booking

━━━━━━━━━━━━━━━━━━━━
▶ STEP 7 — SEED TEST DATA

Managed RAP will create rows later through the BO, but you want something to look at now. The small class ZCL_RAP_TRAVEL_DATA_GEN (implements if_oo_adt_classrun) deletes and inserts a few Travel and Booking rows into your own Z tables — never standard SAP tables. Run it with F9 in ADT. In production-bound code you would never insert directly; this is a developer-only seeding utility kept in the development package.

━━━━━━━━━━━━━━━━━━━━
▶ TROUBLESHOOTING

| Symptom | Likely cause | Fix |
|---|---|---|
| "Reference field for CURR field missing" | Amount without currency link | Add @Semantics.amount.currencyCode in table and CDS |
| "Composition target has no association to parent" | Child missing association to parent | Add it with correct ON condition |
| Cycle activation error | Activating root alone | Mass-activate both entities |
| Data Preview shows no bookings | parent_uuid not filled in test data | Fix generator so bookings carry the Travel UUID |
| Alias rename breaks later | Draft table mirrors old alias | Regenerate draft table after renames (Part 3) |
| sysuuid_x16 unknown in ABAP Cloud | Wrong type spelling | Use sysuuid_x16 (data element) — released in ABAP Cloud |

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

You are ready for Part 3 when:

• [ ] ZRAP_TRAVEL and ZRAP_BOOKING are active with UUID keys, business ID, admin and ETag fields, and linked currency.
• [ ] ZI_RAP_Travel is a root view entity with composition [0..*] to ZI_RAP_Booking.
• [ ] ZI_RAP_Booking has association to parent with an ON condition on ParentUUID.
• [ ] Data Preview on the root navigates to bookings.
• [ ] You know the names ZRAP_TRAV_D / ZRAP_BOOK_D will be generated from the BDEF.

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

Add a Description field (abap.char(256)) to the Travel table and CDS, and an optional association _Agency (or any released master-data view available in your release) with [0..1] cardinality. Reactivate, then confirm in Data Preview that the association is navigable but does not appear as a composition.

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

"In RAP I start from the tree: a root CDS view entity with a composition to its children, each child with an association to parent. I use UUID technical keys plus a separate business ID, annotate admin and ETag timestamps with @Semantics so the managed framework fills them, link every amount to a currency, and let ADT generate draft tables from the behavior definition so field names stay in sync."

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

[Part 3: Managed Behavior, Draft, Locking, ETag and Numbering](/lessons/rap-bootcamp-part-3-managed-behavior-draft) turns this data model into a transactional business object.

On a customer project the team modelled "Travel" with a composite semantic key (agency + travel number) and later needed to create travels from an external channel before a number was assigned. Switching to a UUID technical key with a separate business TravelID late in the project meant regenerating draft tables, reworking the projection and retesting the UI. Starting with UUID keys, a separate readable ID, @Semantics admin fields and currency-linked amounts — exactly the model in this part — avoided that rework on the next object.

• Using a normal association instead of association to parent in the child — the BDEF later cannot declare the child as composed.
• Activating the root alone and fighting the cycle error instead of mass-activating.
• Declaring amounts without a currency reference; activation fails or the UI shows unformatted values.
• Hand-writing draft tables with DB-table field names instead of CDS alias names.
• Using the business ID as the key and then needing early numbering in every create path.
• Inserting test data into standard SAP tables — only seed your own Z tables, and only in development.
• Forgetting local_last_changed_at on the child, which leaves no field for its local ETag.

• Model the tree on paper first: root, children, keys, business IDs, admin fields.
• Use UUID technical keys plus a separate business ID for managed scenarios.
• Annotate admin and ETag timestamps with @Semantics so the framework fills them.
• Link every amount to a currency in both table and CDS.
• Mass-activate root and child together.
• Generate draft tables from the BDEF quick fix, never by hand.
• Keep naming consistent (ZRAP_* tables, ZI_RAP_* interface views) across the whole BO.

Expect: "What is the difference between composition and association in RAP?" — composition defines the BO tree (ownership, cascade delete, create-by-association, lock and ETag inheritance); association is navigation only. Also: "Why UUID keys?" — framework-managed early numbering, no number-range dependency, simple draft handling; a readable business ID is still shown to users.