RAP Business Objects Part 1: Designing the BO — Root, Children and Boundaries

📌 KEY POINTS
✅ A BO is one transactional boundary: locked, checked and saved together.
✅ Composition only for parts with no own lifecycle.
✅ Everything else (supplier, product) is referenced by association.
⚠️ Oversized trees cause lock conflicts and heavy drafts.

▶ WHAT THIS SERIES COVERS
This series gives you the map of a RAP business object (BO). The detailed build steps are in the Managed RAP and Unmanaged RAP series; here you learn the concepts that make those steps make sense.

• Part 1 — designing the BO: root, children, boundaries (this lesson)
• Part 2 — managed vs unmanaged: the decision
• Part 3 — the transactional buffer, the save sequence and the RAP LUW
• Part 4 — locking, ETags and concurrency
• Part 5 — authorization, feature control and messages

━━━━━━━━━━━━━━━━━━━━
▶ WHAT A RAP BUSINESS OBJECT IS
A business object is a real-world thing your application manages as one unit: a purchase request, a sales order, a travel booking. Technically it is a tree of CDS entities plus a behavior definition that says what may happen to the tree.
The most important property: a BO is a transactional boundary. Everything inside the tree is locked together, checked together and saved together — all or nothing.

━━━━━━━━━━━━━━━━━━━━
▶ THE TREE

• Root entity — the anchor ("define root view entity"). Its key identifies the whole BO instance. Locks, ETag master and authorization master usually sit here.
• Child entities — parts that belong to the root and cannot exist without it (items, schedule lines, notes). Declared with "composition" in the parent and "association to parent" in the child.
• Deeper levels are allowed: root → item → schedule line.
• Everything outside the tree is only referenced with a normal association: customer, material, currency, another BO.

━━━━━━━━━━━━━━━━━━━━
▶ HOW TO DECIDE WHAT BELONGS IN THE TREE
Ask for each candidate entity:

1. Does it have its own lifecycle? If it can be created, changed or deleted independently (a customer, a product), it is a separate BO — reference it.
2. Must it be consistent with the root in the same transaction? If an item change must be validated together with the header (totals, status), it belongs in the tree.
3. Who edits it and when? If two different teams edit it at different times, putting it in the tree causes unnecessary locking of the whole BO.
4. How big can it get? A tree with thousands of children per root makes every lock and draft heavy — consider a separate BO.

Rule of thumb: keep the tree as small as consistency requires.

KEYS

• Use a technical UUID key for every entity (generated by the framework in managed RAP).
• Children carry the parent's key as a foreign key field (e.g. RequestUUID in the item).
• Add a human-readable semantic number on the root (e.g. RequestID) for users (Managed RAP Part 2).

━━━━━━━━━━━━━━━━━━━━
▶ LAYERS AND NAMING
A consistent naming scheme makes every RAP project easier:

• Tables: ZPR_HEAD, ZPR_ITEM (plus draft tables later).
• BO base views: ZR_PurchReq (root), ZR_PurchReqItem (child) with a behavior definition ZR_PurchReq.
• Behavior pool: ZBP_R_PURCHREQ.
• Projections per consumer: ZC_ for UI, ZA_ (or similar) for APIs.
• Service definition ZUI_… / ZAPI_…, binding with _O4 suffix.

━━━━━━━━━━━━━━━━━━━━
▶ STEP BY STEP — DESIGN BEFORE CODE

1. Write down the business object in one sentence ("A purchase request with its items, approved as one unit").
2. List candidate entities and apply the four questions.
3. Draw the tree: root, children, references.
4. Decide keys (UUID + semantic number).
5. Decide the implementation type (Part 2).
6. Only then create tables and CDS views (Managed RAP Part 1).

━━━━━━━━━━━━━━━━━━━━
▶ WHAT YOU HAVE AFTER PART 1
A method to draw a correct BO tree. The code example shows how such a design is expressed in CDS and in the first lines of a behavior definition.

A team modeled "Project" as a RAP BO with WBS elements, tasks, time entries and documents all as compositions under the project root. It worked in the demo. In production, every time an employee booked a time entry, the whole project was locked, so project managers could not edit the project for hours, and draft sessions became very large.
In a redesign, time entries and documents became separate BOs with an association to the project, because they have their own lifecycle and editors. The project BO kept only WBS elements and tasks, which really must be consistent with the project header. Lock conflicts disappeared and response times improved.

• Putting every related entity into the composition tree "because it belongs to it".
• Modeling a reference (customer, product) as a composition.
• Using a normal association where the child really has no life without the parent.
• Designing without a UUID key, then struggling with numbering and draft.
• Starting with tables and code before drawing the tree.
• Mixing naming conventions so nobody can tell base views from projections.

• Treat the BO as a transactional boundary: lock, check and save together.
• Keep the tree as small as consistency requires; reference everything with its own lifecycle.
• UUID keys for all entities, a semantic number on the root.
• Agree a naming convention (ZR_, ZC_, ZBP_, ZUI_) at project start.
• Draw and review the tree with the functional expert before building.

Questions: "What is a RAP business object?", "How do you decide what belongs in the composition tree?", "What is the difference between composition and association?"
Strong answer: a BO is a tree of CDS entities with behavior, forming one transactional boundary; the root carries lock, ETag and authorization master, children depend on it. Include an entity in the tree only if it has no independent lifecycle and must be consistent with the root in one transaction; everything else is referenced via association. Mention the cost of oversized trees (locking, draft size) — a sign of design experience.