RAP Basics Part 10: EML — Entity Manipulation Language

📌 KEY POINTS
✅ EML is the ABAP syntax for RAP BOs: READ ENTITIES, MODIFY ENTITIES, COMMIT ENTITIES, ROLLBACK ENTITIES.
✅ Changes go to the transactional buffer first; nothing is on the database until COMMIT ENTITIES (outside the BO).
✅ %cid (content ID) links a new instance to its children in the same request before keys exist; mapped returns the final keys.
✅ Inside the behavior pool use EML IN LOCAL MODE and never COMMIT ENTITIES; outside (reports, jobs, other BOs' save) you commit.
⚠️ Ignoring failed and reported after MODIFY or COMMIT hides errors — always check them.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE WE ARE
Part 9 used EML inside the behavior pool. Here is the full language and its use from outside the BO.

━━━━━━━━━━━━━━━━━━━━
▶ 1. READ ENTITIES

• READ ENTITIES OF zi_travel ENTITY Travel FIELDS ( … ) WITH … RESULT lt_travel.
• Read by association: ENTITY Travel BY \_Booking ALL FIELDS WITH … RESULT lt_booking.
• Reads through the buffer — sees uncommitted changes of the same LUW.

━━━━━━━━━━━━━━━━━━━━
▶ 2. MODIFY ENTITIES

• CREATE FIELDS ( … ) WITH VALUE #( ( %cid = 'T1' … ) ).
• CREATE BY \_Booking … ( %cid_ref = 'T1' %target = … ) — children for a new parent.
• UPDATE FIELDS ( … ) WITH …; DELETE FROM …; EXECUTE acceptTravel FROM ….
• Response: MAPPED ls_mapped FAILED ls_failed REPORTED ls_reported.

━━━━━━━━━━━━━━━━━━━━
▶ 3. COMMIT ENTITIES

• COMMIT ENTITIES RESPONSE OF zi_travel FAILED … REPORTED ….
• Triggers the save sequence (finalize, check_before_save, save).
• Check sy-subrc and failed; ROLLBACK ENTITIES on error.
• Not allowed inside behavior pool handler/saver methods.

━━━━━━━━━━━━━━━━━━━━
▶ 4. WHERE EML IS USED

• Inside the BO: determinations/actions (IN LOCAL MODE).
• Outside: background jobs, migration programs, other BOs, unit tests.
• Consuming SAP released BOs (e.g. I_SalesOrderTP) from custom code — the clean-core alternative to BAPIs.

━━━━━━━━━━━━━━━━━━━━
▶ 5. PRIVILEGED AND LOCAL MODE

• IN LOCAL MODE: only inside the implementing BO; skips feature/authorization checks.
• PRIVILEGED: skip authorization for BOs that support it (with a privileged mode in the BDEF).

━━━━━━━━━━━━━━━━━━━━
▶ STEP BY STEP

1. Write a report that creates a travel with two bookings using %cid.
2. Check failed/reported after MODIFY.
3. COMMIT ENTITIES and check the response.
4. Read the created travel with READ ENTITIES and display it.

✅ CHECKPOINT: the report creates a travel with bookings, prints the new TravelID, and shows messages if a validation fails.

A migration team loaded 40,000 open travel requests into a new RAP BO with a report that looped over the legacy file and called MODIFY ENTITIES plus COMMIT ENTITIES per record, without checking the response. The run finished "successfully", but 3,100 records were missing — validations had rejected them and nobody read failed/reported. The architect rewrote the program to process packages of 500 records per MODIFY/COMMIT, collect failed/reported into an error log with the legacy key (via %cid), and rerun only failed records. Runtime dropped from 6 hours to 50 minutes and every rejected record was explained.

• Not checking failed/reported after MODIFY ENTITIES and COMMIT ENTITIES.
• Calling COMMIT ENTITIES inside a determination, action or saver method.
• Committing per record in mass programs instead of in packages.
• Forgetting %cid/%cid_ref when creating parent and children in one request.
• Using IN LOCAL MODE outside the implementing BO (not allowed).

• Always evaluate mapped, failed and reported; log messages with the business key.
• Commit in packages for mass processing.
• Use %cid values derived from the source key to trace errors.
• Prefer EML on released SAP BOs over BAPIs in S/4HANA clean-core development.
• Use EML in ABAP Unit tests to test BO behavior end to end.

Questions: "What is EML?", "What is %cid used for?", "Can you use COMMIT ENTITIES in a determination?"
Strong answer: EML is the ABAP language for RAP BOs — READ/MODIFY/COMMIT/ROLLBACK ENTITIES — working on the transactional buffer. %cid identifies new instances before keys exist so children can be created in the same request; mapped returns the final keys. COMMIT ENTITIES triggers the save sequence and is only allowed outside the BO's handler and saver methods; results must be checked via failed/reported and sy-subrc.