EML Part 2: %cid, %cid_ref, MAPPED, FAILED and REPORTED

📌 KEY POINTS
✅ %cid names a new instance; %cid_ref refers to it.
✅ MAPPED returns new keys; FAILED has %fail-cause; REPORTED has messages.
✅ Deep create: header + items in one MODIFY.
⚠️ Evaluate responses after MODIFY and after COMMIT.

▶ WHERE WE ARE
Part 1 introduced the statements. When you create several related instances at once, you need a way to refer to things that do not have keys yet, and afterwards you need to know what happened to each instance. That is the job of content IDs and response parameters.

1. %CID — A NAME FOR SOMETHING THAT HAS NO KEY YET

When you create an instance, its key may be assigned by the BO (UUID, number range, late numbering). You cannot refer to it by key within the same request, so you give it a content ID: %cid = 'REQ1'. %cid values are your choice, must be unique within one request, and live only for that request.

1. %CID_REF — REFERRING TO A NEW INSTANCE

In the same MODIFY, other operations can refer to the new instance through %cid_ref:

• CREATE BY \_Item … %cid_ref = 'REQ1' — create items for the request being created (deep create).
• EXECUTE submit FROM VALUE #( ( %cid_ref = 'REQ1' ) ) — execute an action on it.
• UPDATE … %cid_ref = 'REQ1' — change it again.

Each item in %target also gets its own %cid so you can find its key in MAPPED.

━━━━━━━━━━━━━━━━━━━━
▶ 3. MAPPED — THE KEYS YOU DID NOT KNOW
After the MODIFY, MAPPED contains one line per created instance per entity: mapped-purchaserequest (with %cid and the key / %tky), mapped-item. Use it to read the new instances, to log their keys, or to pass them on. With late numbering, MAPPED contains %pid during the interaction phase; final keys exist only after the save (use COMMIT ENTITIES … and CONVERT KEY or read the saved data).

━━━━━━━━━━━━━━━━━━━━
▶ 4. FAILED — WHAT DID NOT WORK

• One component per entity: failed-purchaserequest, failed-item.
• Each line identifies the instance (%tky, or %cid for creates) and %fail-cause: not_found, unauthorized, locked, conflict (e.g. ETag), disabled (feature control), readonly, unspecific.
• An instance in FAILED was not processed; the rest of the request may have been.

━━━━━━━━━━━━━━━━━━━━
▶ 5. REPORTED — WHY

• Messages per entity (reported-purchaserequest with %tky / %cid and %msg), plus reported-%other for unbound messages.
• %msg is an object implementing if_abap_behv_message; get the text with %msg->if_message~get_text( ) and the severity with %msg->m_severity.
• %element shows which fields a message refers to.

━━━━━━━━━━━━━━━━━━━━
▶ 6. EVALUATE AT THE RIGHT TIME

• After MODIFY: interaction-phase results — authorization, feature control, prechecks, action failures, determinations on modify.
• After COMMIT ENTITIES RESPONSE: save-phase results — validations and on-save determinations. A request that passed MODIFY can still fail at COMMIT.

Programs should evaluate both.

━━━━━━━━━━━━━━━━━━━━
▶ 7. DEEP CREATE — ALL IN ONE STATEMENT
A header with items is created in one MODIFY: CREATE for the root with %cid, CREATE BY \_Item with %cid_ref and %target. RAP processes them together; either the whole tree passes the save sequence or nothing is saved.

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

1. Run the code example: deep create with two items plus an action on the new request.
2. Print MAPPED to see the keys, then force a failure (omit the description) and print FAILED and REPORTED after COMMIT.
3. Write a reusable method that converts FAILED/REPORTED into a readable log.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT YOU HAVE AFTER PART 2
You can create complex data in one call and understand the outcome of every instance. Part 3 explains IN LOCAL MODE.

A data migration program created purchase request headers in one MODIFY, committed, then tried to find the new headers by selecting the latest rows from the table to attach items. Under parallel load it attached items to the wrong headers.
Rewriting it as a deep create — header with %cid, items with %cid_ref in the same MODIFY — removed the guessing completely. MAPPED gave the program the exact keys for its log, and a failed validation now rejected a header together with its items instead of leaving headers without items.

• Guessing new keys by selecting "the latest" rows instead of using MAPPED.
• Reusing the same %cid twice in one request.
• Confusing %cid (name of a new instance) with %cid_ref (reference to it).
• Evaluating only MODIFY responses and ignoring COMMIT ENTITIES RESPONSE.
• Ignoring %fail-cause, so every failure looks the same.
• Expecting final late-numbering keys in MAPPED before the save.

• Create related data in one deep MODIFY with %cid / %cid_ref.
• Give every created instance a unique, readable %cid (e.g. row number of the input).
• Evaluate FAILED and REPORTED after MODIFY and after COMMIT.
• Build one reusable method that turns responses into a log.
• Use %fail-cause to react correctly (retry on locked, reload on conflict).

Questions: "What is %cid and %cid_ref?", "How do you do a deep insert in EML?", "What is in MAPPED, FAILED and REPORTED?", "When do validation errors appear in EML?"
Strong answer: %cid names a new instance within one request; %cid_ref refers to it from other operations such as create-by-association or an action. MAPPED returns keys per %cid, FAILED lists failed instances with %fail-cause, REPORTED carries messages. Interaction-phase failures show after MODIFY; validation failures after COMMIT ENTITIES RESPONSE. A deep create keeps the tree consistent in one transaction.