EML Cheat Sheet — RAP Business Object Consumption

Use this sheet from Lesson 12 onward. Browse all cheat sheets.

Replace ### with your own student/group suffix.

Course examples use:

Root BO:       ZR_RESERVATION_###
Entity alias:  Reservation
Technical key: Uuid

---

1. Mental model

EML stands for Entity Manipulation Language.

Use it to work with a RAP Business Object:

ABAP Consumer
     ↓
    EML
     ↓
RAP Business Object
     ↓
Transactional Buffer
     ↓
Persistence

For normal RAP consumers:

EML → BO

not:

direct SQL → RAP-owned table

---

2. Quick command map

Goal	EML
Read BO data	READ ENTITIES
Create	MODIFY ENTITIES ... CREATE
Update	MODIFY ENTITIES ... UPDATE
Delete	MODIFY ENTITIES ... DELETE
Execute action	MODIFY ENTITIES ... EXECUTE
Save transaction	COMMIT ENTITIES
Discard transaction	ROLLBACK ENTITIES
Inspect features/permissions	GET PERMISSIONS
Provider-side BO access	... IN LOCAL MODE

---

External Consumer EML

Normal consumer classes such as:

ZCL_RESV_EML_###
ZCL_RESV_RULES_###
ZCL_RESV_ACTIONS_###

use normal EML.

Do not add IN LOCAL MODE to an ordinary external consumer.

---

3. READ — selected fields

READ ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    FIELDS (
      Uuid
      ReservationNo
      CustomerName
      Status )
    WITH VALUE #(
      ( Uuid = uuid )
    )
  RESULT DATA(reservations)
  FAILED DATA(failed_read).

Think:

BO → entity → fields → key(s) → result

---

4. READ — all fields

READ ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    ALL FIELDS
    WITH VALUE #( ( Uuid = uuid ) )
  RESULT DATA(reservations)
  FAILED DATA(failed_read).

Useful for testing and inspecting administrative fields.

Prefer selected fields when you only need a few values.

---

5. CREATE

MODIFY ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    CREATE FIELDS (
      ReservationNo
      CustomerName
      ReservationDate
      Fee
      CurrencyCode )
    WITH VALUE #(
      ( %cid            = 'RES_1'
        ReservationNo   = '98000001'
        CustomerName    = 'EML Student'
        ReservationDate = cl_abap_context_info=>get_system_date( )
        Fee              = '150.00'
        CurrencyCode     = 'EUR' )
    )
  MAPPED DATA(mapped)
  FAILED DATA(failed)
  REPORTED DATA(reported).

For a managed UUID key, do not provide Uuid yourself.

---

6. %cid

%cid is the consumer-side temporary identifier for a create request.

%cid = 'RES_1'

Think:

%cid
  ↓
MAPPED
  ↓
generated BO key

---

7. Get the generated UUID from MAPPED

Prefer correlation by %cid:

DATA(uuid) =
  mapped-reservation[ %cid = 'RES_1' ]-Uuid.

Safer:

IF line_exists(
     mapped-reservation[ %cid = 'RES_1' ] ).

  DATA(uuid) =
    mapped-reservation[ %cid = 'RES_1' ]-Uuid.

ENDIF.

Do not rely on mapped-table row order unless you deliberately designed for it.

---

8. UPDATE

MODIFY ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    UPDATE FIELDS (
      Status
      Notes )
    WITH VALUE #(
      ( Uuid   = uuid
        Status = 'C'
        Notes  = 'Updated with EML' )
    )
  FAILED DATA(failed)
  REPORTED DATA(reported).

UPDATE FIELDS makes the intended changed fields explicit.

---

9. DELETE

MODIFY ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    DELETE FROM VALUE #(
      ( Uuid = uuid )
    )
  FAILED DATA(failed)
  REPORTED DATA(reported).

Use the BO technical key.

Do not replace normal RAP consumption with direct table DELETE.

---

10. EXECUTE an action

If the BDEF declares confirm:

MODIFY ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    EXECUTE confirm
      FROM VALUE #(
        ( Uuid = uuid )
      )
    RESULT DATA(action_result)
  FAILED DATA(failed)
  REPORTED DATA(reported).

For an action declared with:

result [1] $self

RESULT contains the changed Reservation instance.

---

RAP Responses

11. MAPPED, FAILED, REPORTED

MAPPED

Key mapping after create/numbering.

Typical use:

%cid → generated Uuid

FAILED

Programmatic failure information.

Think:

Which instance failed?

REPORTED

Messages and reported information.

Think:

Why did it fail?
What should the consumer know?

---

12. FAILED vs REPORTED

FAILED
→ this instance/operation failed

REPORTED
→ explanation/message/context

A validation commonly fills both.

A message alone is not the same as marking an instance failed.

---

13. Inspect responses while learning

out->write( mapped ).
out->write( failed ).
out->write( reported ).

In production logic, react to the relevant response instead of only printing it.

---

RAP Transaction

14. Transactional buffer

MODIFY ENTITIES
      ↓
transactional buffer
      ↓
READ ENTITIES can see current transaction state
      ↓
COMMIT or ROLLBACK

A successful MODIFY ENTITIES is not the same as a completed save.

---

15. COMMIT

COMMIT ENTITIES
  RESPONSE OF ZR_Reservation_###
    FAILED DATA(failed_commit)
    REPORTED DATA(reported_commit).

Use this to trigger the RAP save sequence and persist successful changes.

Check:

FAILED
REPORTED
sy-subrc

---

16. ROLLBACK

ROLLBACK ENTITIES.

Use it to discard the current RAP transaction.

Typical test:

UPDATE
↓
READ changed buffer state
↓
ROLLBACK ENTITIES
↓
READ original persisted state

---

17. Interaction phase vs save phase

MODIFY ENTITIES
→ interaction-phase response

COMMIT ENTITIES
→ save-phase response

Important pattern:

MODIFY create succeeds
        ↓
instance enters transaction
        ↓
COMMIT ENTITIES
        ↓
on-save validation fails
        ↓
FAILED + REPORTED

So:

successful MODIFY ≠ successful save

---

Special % Components

18. %cid

create-request correlation ID

Used heavily with:

CREATE
MAPPED

---

19. %tky

transactional key

Common provider-side use:

%tky = reservation-%tky

Use it for the current BO instance identity inside behavior implementation.

---

20. %param

Used for action/function result parameters.

Example for result [1] $self:

result = VALUE #(
  FOR reservation IN reservations
  ( %tky   = reservation-%tky
    %param = reservation )
).

---

21. %element

Targets a message at a field.

%element-CustomerName = if_abap_behv=>mk-on

Think:

this message belongs to CustomerName

---

22. %features

Used in dynamic feature control.

Examples:

%features-%action-confirm
%features-%field-Fee

Remember:

fc-o = operation/action feature
fc-f = field feature

---

Provider-Side EML

Provider-side EML is used inside the Behavior Pool for logic such as:

determinations
validations
actions
feature control
authorization handlers

---

23. IN LOCAL MODE

Provider-side read:

READ ENTITIES OF ZR_Reservation_### IN LOCAL MODE
  ENTITY Reservation
    FIELDS ( Status )
    WITH CORRESPONDING #( keys )
  RESULT DATA(reservations).

Provider-side modify:

MODIFY ENTITIES OF ZR_Reservation_### IN LOCAL MODE
  ENTITY Reservation
    UPDATE FIELDS ( Status )
    WITH updates.

Use local mode for BO implementation logic, not as a shortcut in ordinary consumer code.

---

24. External vs provider-side EML

Context	Use
External consumer class	Normal EML
Behavior Pool implementation	EML IN LOCAL MODE
External transaction end	COMMIT ENTITIES / ROLLBACK ENTITIES
RAP handler method	Do not commit/rollback the transaction

A handler participates in the RAP transaction; it does not own the external transaction boundary.

---

BDEF-Derived Types

25. Create request type

DATA creates
  TYPE TABLE FOR CREATE ZR_Reservation_###.

Example:

creates = VALUE #(
  ( %cid            = 'RES_1'
    ReservationNo   = '98000001'
    CustomerName    = 'Student'
    ReservationDate = cl_abap_context_info=>get_system_date( )
    Fee              = '100.00'
    CurrencyCode     = 'EUR' )
).

Pass it with:

WITH creates

---

26. Update request type

DATA updates
  TYPE TABLE FOR UPDATE ZR_Reservation_###.

Example:

updates = VALUE #(
  ( Uuid   = uuid
    Status = 'C' )
).

---

27. Permission-derived types

Useful types include:

TYPE TABLE FOR PERMISSIONS KEY
TYPE STRUCTURE FOR PERMISSIONS REQUEST
TYPE STRUCTURE FOR PERMISSIONS RESULT

These are useful for larger or dynamic permission requests.

---

Feature Control / Permissions

28. GET PERMISSIONS — instance features

GET PERMISSIONS ONLY INSTANCE FEATURES OF ZR_Reservation_###
  ENTITY Reservation
    FROM VALUE #(
      ( Uuid = uuid )
    )
    REQUEST VALUE #(
      %action-confirm     = if_abap_behv=>mk-on
      %action-cancel      = if_abap_behv=>mk-on
      %field-Fee          = if_abap_behv=>mk-on
      %field-CurrencyCode = if_abap_behv=>mk-on
    )
  RESULT DATA(permissions)
  FAILED DATA(failed_permissions)
  REPORTED DATA(reported_permissions).

Use it to ask:

Is this action enabled?
Is this field editable?

for a specific instance.

---

29. Common feature constants

Actions / operations:

if_abap_behv=>fc-o-enabled
if_abap_behv=>fc-o-disabled

Fields:

if_abap_behv=>fc-f-unrestricted
if_abap_behv=>fc-f-read_only

---

Common EML Patterns

30. Create → mapped key → commit

MODIFY ENTITIES CREATE
      ↓
check FAILED
      ↓
read generated key from MAPPED
      ↓
COMMIT ENTITIES
      ↓
check save FAILED / REPORTED

---

31. Create → read before commit

CREATE
  ↓
MAPPED gives UUID
  ↓
READ ENTITIES using UUID
  ↓
see transactional-buffer state
  ↓
COMMIT

Useful for proving:

managed numbering
determinations
transactional buffer

---

32. Update → rollback test

READ original state
      ↓
MODIFY ENTITIES UPDATE
      ↓
READ changed buffer state
      ↓
ROLLBACK ENTITIES
      ↓
READ original persisted state

---

33. Validation test

MODIFY invalid data
      ↓
interaction response
      ↓
COMMIT ENTITIES
      ↓
on-save validation
      ↓
FAILED + REPORTED
      ↓
ROLLBACK ENTITIES

---

34. Action + feature test

GET PERMISSIONS
      ↓
EXECUTE action
      ↓
inspect RESULT
      ↓
COMMIT ENTITIES
      ↓
GET PERMISSIONS again

---

Common Mistakes

35. Direct SQL modification of RAP persistence

Avoid normal consumer code such as:

UPDATE zresv_###

It can bypass:

validations
determinations
actions
authorization
feature control
messages
transactional buffer
save sequence

Use EML.

---

36. Supplying a managed read-only UUID

If the BDEF has:

field ( numbering : managed, readonly ) Uuid;

use:

%cid → MAPPED → generated Uuid

Do not provide Uuid as normal create input.

---

37. Forgetting COMMIT

MODIFY ENTITIES

does not mean:

transaction successfully persisted

Use COMMIT ENTITIES when the consumer wants to complete the transaction.

---

38. Ignoring save responses

On-save validations can fail at:

COMMIT ENTITIES

Inspect save-phase:

FAILED
REPORTED

not only the earlier modify response.

---

39. Using IN LOCAL MODE in external code

External consumer → normal EML
Provider          → EML IN LOCAL MODE

---

40. Committing inside a Behavior Pool handler

Do not use these inside normal RAP handler methods:

COMMIT ENTITIES
ROLLBACK ENTITIES
COMMIT WORK
ROLLBACK WORK

The consumer/runtime owns the transaction boundary.

---

41. Parsing message text to detect failure

Do not use message text as your failure API.

Use:

FAILED

for programmatic failure state.

Use:

REPORTED

for explanation.

---

42. Confusing %cid and %tky

%cid
→ create-request correlation ID

%tky
→ transactional BO instance identity

---

Certification Quick Recall

43. Time-pressure memory map

READ
→ READ ENTITIES

CREATE / UPDATE / DELETE / ACTION
→ MODIFY ENTITIES

Create correlation
→ %cid

Generated key
→ MAPPED

Failure
→ FAILED

Message
→ REPORTED

Transactional identity
→ %tky

Action result
→ %param

Field message target
→ %element

Provider BO access
→ IN LOCAL MODE

Persist
→ COMMIT ENTITIES

Discard
→ ROLLBACK ENTITIES

Runtime feature query
→ GET PERMISSIONS

---

44. One complete mini lifecycle

" 1. CREATE
MODIFY ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    CREATE FIELDS (
      ReservationNo
      CustomerName
      ReservationDate
      Fee
      CurrencyCode )
    WITH VALUE #(
      ( %cid            = 'RES_1'
        ReservationNo   = '98000001'
        CustomerName    = 'EML Student'
        ReservationDate = cl_abap_context_info=>get_system_date( )
        Fee              = '100.00'
        CurrencyCode     = 'EUR' )
    )
  MAPPED DATA(mapped)
  FAILED DATA(failed_create)
  REPORTED DATA(reported_create).

IF failed_create IS NOT INITIAL.
  ROLLBACK ENTITIES.
  RETURN.
ENDIF.

DATA(uuid) =
  mapped-reservation[ %cid = 'RES_1' ]-Uuid.


" 2. READ CURRENT TRANSACTION STATE
READ ENTITIES OF ZR_Reservation_###
  ENTITY Reservation
    ALL FIELDS
    WITH VALUE #( ( Uuid = uuid ) )
  RESULT DATA(before_commit)
  FAILED DATA(failed_read).


" 3. SAVE
COMMIT ENTITIES
  RESPONSE OF ZR_Reservation_###
    FAILED DATA(failed_commit)
    REPORTED DATA(reported_commit).

Read it as:

create through BO
→ get generated identity
→ inspect transactional state
→ save through RAP

---

45. Final rule

When working with a RAP-owned object, ask:

Am I working with the Business Object,
or bypassing it and working directly with its table?

For normal transactional application code:

choose the Business Object
→ use EML