EML Part 1: What EML Is — READ, MODIFY and COMMIT ENTITIES

📌 KEY POINTS
✅ READ ENTITIES, MODIFY ENTITIES, COMMIT ENTITIES, ROLLBACK ENTITIES, GET PERMISSIONS.
✅ EML runs the full BO behavior — unlike direct table updates.
✅ UPDATE FIELDS ( … ) sets %control for partial updates.
⚠️ Validations run at COMMIT ENTITIES, not at MODIFY.

▶ WHAT THIS SERIES COVERS

• Part 1 — what EML is: READ, MODIFY, COMMIT (this lesson)
• Part 2 — %cid, %cid_ref, MAPPED, FAILED and REPORTED
• Part 3 — IN LOCAL MODE: what it bypasses and when it is safe
• Part 4 — calling other BOs, COMMIT ENTITIES and ROLLBACK ENTITIES
• Part 5 — testing with EML and transactional consistency

━━━━━━━━━━━━━━━━━━━━
▶ WHAT EML IS
Entity Manipulation Language is part of ABAP. It is the type-safe API to any RAP business object — your own or SAP's released ones. Instead of writing to tables, you ask the business object to do something, and it runs its full behavior: authorization, feature control, determinations, validations, locking, numbering, draft.
The OData layer uses the same mechanism internally, so an EML call and a Fiori action on the same BO behave identically.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE EML IS USED

• Inside behavior implementations — to read and change your own BO (with IN LOCAL MODE, Part 3).
• In ABAP programs, jobs, console classes — to create or change BO instances from code.
• In other BOs — to call another business object (Part 4).
• In ABAP Unit tests (Part 5).
• In clean-core development — to change SAP data through SAP's released RAP BO interfaces instead of BAPIs or table updates.

━━━━━━━━━━━━━━━━━━━━
▶ THE STATEMENTS

• READ ENTITIES OF <bo> ENTITY <alias> FIELDS ( … ) | ALL FIELDS WITH <keys> RESULT <result>. — read instances (buffer state included). BY \_Assoc reads associated instances.
• MODIFY ENTITIES OF <bo> ENTITY <alias> CREATE | UPDATE | DELETE | EXECUTE <action> … — change instances or execute actions. CREATE BY \_Assoc creates children.
• COMMIT ENTITIES [RESPONSE OF <bo> FAILED … REPORTED …]. — triggers the save sequence and database commit. Only outside behavior implementations.
• ROLLBACK ENTITIES. — discards the transactional buffer.
• GET PERMISSIONS OF <bo> ENTITY <alias> … — asks which operations are allowed (authorization and feature control) without executing them.
• Functions are executed via READ ENTITIES … EXECUTE <function>.

━━━━━━━━━━━━━━━━━━━━
▶ SHORT FORM AND LONG FORM

• Short form: one BO, one or more entities — "MODIFY ENTITIES OF zr_purchreq ENTITY PurchaseRequest UPDATE …".
• Long form: several BOs in one statement — "MODIFY ENTITIES ENTITY zr_purchreq … ENTITY zr_other …" — rarely needed.
• Dynamic form: "MODIFY ENTITIES OPERATIONS op_table" — when the BO or operation is known only at runtime (generic tools).

━━━━━━━━━━━━━━━━━━━━
▶ INPUT: TABLES OF INSTANCES
Every operation takes a table:

• CREATE: rows with %cid and field values; FIELDS ( … ) says which fields you supply.
• UPDATE: rows with the key (%tky) and values; FIELDS ( … ) sets %control, so only these fields are changed.
• DELETE / EXECUTE: rows with keys (and %param for action parameters).

Using FIELDS ( … ) WITH VALUE #( … ) is the safest form because %control is set automatically.

━━━━━━━━━━━━━━━━━━━━
▶ OUTPUT: RESPONSE PARAMETERS

• MAPPED — keys assigned to new instances (%cid → key).
• FAILED — instances that could not be processed, with %fail-cause.
• REPORTED — messages.
• RESULT — for READ and for actions with result.

Always evaluate FAILED and REPORTED (Part 2).

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

1. Create a class implementing if_oo_adt_classrun.
2. Paste the code example; adapt the BO name.
3. Run with F9: create, read, update, execute an action, commit, and print the results.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT YOU HAVE AFTER PART 1
The EML vocabulary. Part 2 goes deep into correlation IDs and responses.

A batch program for mass-creating purchase requests from a spreadsheet inserted rows directly into the BO's tables with INSERT. The requests appeared in the Fiori app, but without status, without request numbers, without change log entries, and some violated validations that the app enforced.
The program was rewritten with EML: MODIFY ENTITIES CREATE for each chunk of 500 rows, COMMIT ENTITIES RESPONSE, and a log of FAILED/REPORTED per row. All determinations and validations now ran exactly as in the UI; invalid rows were reported back instead of silently created.

• Writing to BO tables directly instead of using EML.
• Ignoring FAILED and REPORTED.
• Using COMMIT ENTITIES inside a behavior implementation.
• Updating with a full structure without FIELDS ( … ), overwriting fields unintentionally.
• Expecting validations to run on MODIFY — they run at COMMIT ENTITIES.
• Using the plain key instead of %tky for draft-enabled BOs.

• Use EML for every change to a RAP BO, including mass programs.
• Always use FIELDS ( … ) WITH VALUE #( … ) so %control is correct.
• Evaluate FAILED/REPORTED after MODIFY and after COMMIT ENTITIES.
• Commit in chunks in mass programs; log per instance.
• Use GET PERMISSIONS to check what is allowed before offering an operation.

Questions: "What is EML?", "Which EML statements exist?", "Why use EML instead of updating tables?"
Strong answer: EML is the ABAP language part for RAP BOs: READ ENTITIES, MODIFY ENTITIES (create, update, delete, execute, create-by-association), COMMIT ENTITIES, ROLLBACK ENTITIES and GET PERMISSIONS. It runs the full BO behavior, so authorization, determinations, validations and locking apply — unlike direct table updates. Mention FIELDS for %control, the response parameters and that validations run at commit.