CDS Annotations Part 5: Troubleshooting Precedence, Metadata and UI Behavior

📌 KEY POINTS
✅ First check the EFFECTIVE annotation (ADT Active Annotations), not the one you wrote.
✅ Then check the service: is the element exposed and the annotation in $metadata?
✅ Then check the client: caches and personalized variants.
⚠️ A higher-layer metadata extension silently overrides your change.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE WE ARE
Parts 1–4 built annotations. When the Fiori app does not show what you annotated, the cause can be in five different places. This lesson gives the order to check them.

━━━━━━━━━━━━━━━━━━━━
▶ 1. IS THE ANNOTATION EFFECTIVE?
Open the view in ADT → context menu → Open With → Active Annotations. It shows, per element, the effective value and its origin (view, metadata extension layer, propagated).
Typical findings:

• Another metadata extension in a higher layer sets a different value.
• The view lacks @Metadata.allowExtensions: true, so your extension is ignored.
• The annotation is at the wrong scope or has a typo (e.g. selectionField without position).
• A propagated annotation from a lower view is winning because yours is not effective.

━━━━━━━━━━━━━━━━━━━━
▶ 2. IS IT ON THE RIGHT VIEW?
The service exposes the projection (ZC_), not the base view (ZR_). Annotations on ZR_ are only visible if propagated. UI annotations belong on the projection or its extension.

━━━━━━━━━━━━━━━━━━━━
▶ 3. IS THE ELEMENT EXPOSED?

• Is the field in the projection's element list?
• Is the entity exposed in the service definition?
• For facets pointing to child tables: is the association redirected and the child entity exposed?
• For value helps: is the value-help entity reachable?\n\n━━━━━━━━━━━━━━━━━━━━\n▶ 4. IS IT IN $METADATA?\nOpen the service's $metadata (…/$metadata) and search for the property or the vocabulary term (UI.LineItem, UI.SelectionFields, Common.ValueList, UI.Facets). If it is missing here, the problem is on the backend; if it is present, the problem is on the client.

━━━━━━━━━━━━━━━━━━━━
▶ 5. IS THE CLIENT SHOWING OLD METADATA?

• Fiori apps and the launchpad cache metadata. Reload with cache cleared, or use the preview in a private window.
• Gateway metadata cache: clear it (e.g. /IWFND/CACHE_CLEANUP on hub systems) when changes are not visible.
• User personalization: a saved variant can hide columns or filters — reset to the standard variant.

━━━━━━━━━━━━━━━━━━━━
▶ 6. BEHAVIOR VS LAYOUT
If a field is shown but not editable, or a button is disabled, it is usually not an annotation problem: check BDEF field characteristics, feature control and authorization.

━━━━━━━━━━━━━━━━━━━━
▶ STEP BY STEP
Use the checklist in the code example for every "annotation not working" ticket and note at which step you found the cause.

✅ CHECKPOINT: you can trace any annotation from source to screen. Next topic: RAP business objects and behavior.

A developer spent a day trying to make a new column appear. The annotation was correct in his metadata extension, and $metadata was even checked on the wrong service version. Following the checklist, Step 1 showed nothing wrong, Step 4 revealed that the field was missing from the projection element list — it existed only in the base view.
After adding the field to the projection, the column appeared. The team added the checklist to their wiki, and similar tickets were resolved in minutes afterwards.

• Checking the annotation you wrote instead of the effective one.
• Annotating the base view instead of the exposed projection.
• Forgetting @Metadata.allowExtensions: true.
• Field or child entity not exposed in the projection or service.
• Not checking $metadata before blaming the UI.
• Cached metadata or personalized variants hiding the change.
• Treating editability or button state as an annotation problem.

• Follow the checklist in order: effective → view → enabled → exposed → $metadata → client.
• Use ADT Active Annotations for every non-trivial case.
• Keep UI annotations only in projection metadata extensions.
• Test in a private window after changes.
• Document common causes in the team wiki.

Questions: "An annotation is not reflected in the Fiori app — how do you analyze it?", "What is annotation precedence?"
Strong answer: check the effective annotation with Active Annotations (layers, view, propagation), confirm it is on the exposed projection with allowExtensions, confirm the element and entity are exposed, check $metadata to split backend from client, then clear caches and reset variants. Distinguish layout issues from behavior (feature control, authorization). Precedence: MDE layers (CUSTOMER highest) over view annotations over propagated ones.