SuperAPI AI Directory

adp-controller-extension

Frontend & websites

View repository

Updated 10-29 13:58

About this skill

SAP Fiori ADP Controller Extension

Drive Runtime Authoring (RTA) in the SAP Fiori adaptation editor through the run_rta_workflow_step MCP tool exposed by fiori-mcp-server. The tool handles browser automation server-side; this skill orchestrates the step sequence and the AI decisions between steps.

Tool boundary. run_rta_workflow_step is a skill-internal dispatcher. Don't call it ad-hoc — the value of this skill is in the AI decision points between steps (control selection, action selection, payload preparation). Calling out of order will fail with a descriptive error.

Prerequisites

  • @sap-ux/fiori-mcp-server running as an MCP server. It provides run_rta_workflow_step and the other fiori-mcp tools this skill drives without it none of the tool calls below resolve. See the package's install/setup instructions: https://www.npmjs.com/package/@sap-ux/fiori-mcp-server
  • Adaptation editor URL (user-provided)
  • A Chromium-based browser the server can launch. Resolution order:
    1. PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH env var (absolute path to a Chromium binary)
    2. PLAYWRIGHT_BROWSER_CHANNEL env var (chrome, msedge, chrome-beta, etc.)
    3. System Google Chrome (default channel)
    4. Playwright-managed Chromium (auto-fallback if 1–3 fail)

Chromium fallback (no system Chrome)

If no system Chrome is found and no env override is set, the server falls back to Playwright's bundled Chromium. Install it once if needed:

npx playwright install chromium

The first install downloads ~120 MB. Subsequent runs reuse the cache. See the Error Handling table for the detection sequence on a start failure.

Tool Contract

A single tool, dispatched by the step argument. site is the editor URL from open_adaptation_editor — pass it on every step. There is no server-side session; the tool locates the browser page by URL.

step site frameId payload returns
start required required ("preview") — { site, frameId, rtaStarted: true }
get_page_actions required carry forward — { registered: RegisteredPageAction[], interactive: InteractiveElement[], interactiveTruncated?: true }
call_page_action required carry forward { id } { result: PageActionRunResult }
press_interactive required carry forward { controlId } { result: PageActionRunResult }
get_overlays required carry forward — { overlays: Overlay[], actionsCatalog: { [actionId]: Action } }
get_context required carry forward { controlId, actionId } { context }
call_action required carry forward { controlId, actionId, actionPayload } { success: boolean }
save required carry forward — { saved: boolean }
restart required carry forward — { site, frameId, rtaStarted: true }
stop required carry forward — { stopped: true }

Overlay = { overlayId, controlId, label, controlType, parentElementId, parentAggregationName, index?, actionIds: string[] } — index is the 0-based position within parentAggregationName and is omitted when the parent/aggregation can't be resolved or the aggregation is single-cardinality. actionIds lists the RTA actions available on this overlay; rich metadata for each id is in the top-level actionsCatalog. Action = { id, label, description?, parameters: [{ name, type, required?, description? }] } — keyed by actionId in actionsCatalog. The catalog is deduplicated across all overlays in a single get_overlays response, so an id appears once even when many overlays expose it. RegisteredPageAction = { id, layer: "framework"|"app", label, description } — high-level page actions contributed by the framework or app (e.g. loadData, navigateToRow, navigateToSection, navigateBack). Only currently-applicable actions are returned. InteractiveElement = { controlId, controlType, label, kind: "button"|"input"|"listItem"|"tab"|"link"|"other" } — best-effort scan of press-able controls in the live view (root view + static area + open dialogs). interactiveTruncated: true on the response means the scan cap (100) was hit and more candidates exist than were returned; surface this to the user when the entry they want isn't in the list rather than concluding it doesn't exist. PageActionRunResult = { status: "ok", note?, data? } | { status: "needs_user_action", reason }.

  • On press_interactive, note describes the observable change detected after the click ("registered actions changed", "ObjectPage section changed", "navigation occurred", "dialog/popover opened or closed", "focus moved") or "no observable state change". The detector probes at 200 / 400 / 800 ms after the click (cumulative ~1.4 s); a "no observable state change" result means the press didn't move any of those signals within that window, not that the press failed. It is a soft hint, not an error — re-check get_page_actions / get_overlays if you expected a context change.
  • On call_page_action, needs_user_action covers two cases: (a) the action's own run() returned that envelope because a precondition (e.g. mandatory filter not set, value help required) can't be met, or (b) run() threw and the server converted the throw into needs_user_action with the error message as reason. The two are indistinguishable from the surface — if reason reads like an exception (TypeError: …, Cannot read property …), treat it as a runtime error rather than a user-resolvable precondition.

For the standard adaptation editor preview iframe, pass frameId: "preview" in the start step.

When to reach for the page-action steps. The six RTA steps (get_overlays → … → save) assume the page is already showing the control to edit. In Fiori Elements apps that often isn't true on first load — a List Report shows no rows until "Go" is pressed; an Object Page is only reachable after picking a row. Use get_page_actions / call_page_action / press_interactive to drive these pre-RTA navigations from the skill instead of asking the user to click manually. See Step 2 — Navigate the app below.

RTA Actions

CTX_ADDXML (fragment insert) and CTX_EXTEND_CONTROLLER (controller attach). Field schemas and disambiguation table: references/rta-actions.md.

Confidence & HITL Gating

Three steps require AI judgment: control selection (Step 4), action selection (Step 5), and payload preparation (Step 8). Full rubric, per-decision thresholds, and gating rules: references/hitl-gating.md.

Workflow

One session per handover (hard rule). Call start (Step 1) exactly once, restart (Step 13) at most once (only after all fragment/controller files have been written to disk), and stop (Step 14) exactly once at the very end, no matter how many changes are requested. Parse the full change list upfront, then run all changes as iterations of Steps 3–9 inside the single session, and save (Step 11) once at the end. Never re-enter Step 1 (start) per change — a fresh start/stop per change is the single most common misuse of this skill. When the handover prompt hands you a list of changes, that entire list is one session, not one session per bullet.

Step 1 — Start RTA

Call run_rta_workflow_step with step: "start", site (the editor URL from open_adaptation_editor), and payload { site, frameId: "preview" }. Verify rtaStarted: true. Pass site and frameId to every subsequent step. On false, wait 3 s and retry once.

Step 2 — Navigate the app to the editing target

When to skip Step 2. If get_overlays already returns the control the user named (the page is on the right view from the start), skip to Step 3. The page-action loop is for navigation, not for editing.

The RTA flow assumes the control to edit is already on screen. For Fiori Elements apps this often isn't true on first load — a List Report shows no rows until the Filter Bar search is triggered; an Object Page is only reachable after picking a row. Drive that navigation through the page-action steps before reaching for get_overlays.

Call step: "get_page_actions". The result has two arrays:

  • registered: high-level, semantic actions contributed by the framework / app (e.g. loadData, navigateToRow, navigateToSection, navigateBack). Each entry is currently applicable — actions whose preconditions don't hold are filtered out server-side.
  • interactive: a best-effort scan of press-able elements (buttons, list items, tabs, …) in the live view + static area + open dialogs. Use this only when nothing in registered fits.

Decision order (always prefer registered over interactive):

  1. Match user intent against registered. If a registered action matches the navigation step you need (e.g. user said "the order details page" and you're on a List Report → loadData then navigateToRow), call step: "call_page_action" with payload: { id }. The action's run() resolves only when the page has settled (table loaded, OP rendered).
  2. Handle needs_user_action. If result.status === "needs_user_action", surface result.reason to the user — typically a precondition the framework can't satisfy itself (mandatory filter not set, value help required). Wait for them to resolve it, then call get_page_actions again.
  3. Fall through to interactive only when no registered action fits. Pick the entry whose label and kind match the user's words and call step: "press_interactive" with payload: { controlId }. The press uses a real user-gesture click and waits best-effort for the page to change.
  4. Loop. After each call_page_action / press_interactive, call get_page_actions again. The registered set is the live signal that you've moved to a new context — e.g. navigateToSection appearing means you're now on an Object Page. Repeat until the editing target is reachable.

interactive is a fallback, not the primary path. A registered action wraps the framework's own knowledge of "what does it mean to load data here"; an interactive press is a generic click. Reach for press_interactive only when (a) registered is empty for what you need, or (b) call_page_action returned needs_user_action for a reason the user is unlikely to resolve themselves (e.g. a confirmation dialog only the LLM can read).

Page-action confidence is shallow. Picking from registered is usually unambiguous (small set, semantic ids). Picking from interactive is closer to control selection — apply the same rubric as Step 4 control selection: if two interactive entries are within 0.10 confidence of each other, ask.

Step 3 — Get overlays

Call step: "get_overlays". Returns the editable controls on the page.

Step 4 — Select target control (AI decision)

Match the user's instruction against the overlays, examples:

  • "the title" → controls with Title or Header in controlType
  • "the table" → sap.ui.table.Table or sap.m.Table
  • "button X" → sap.m.Button with matching label
  • "toolbar" → sap.m.Toolbar or sap.m.OverflowToolbar

Template handling

In RTA, changes are always made on template clones and mapped to the template internally. When you want to change a template of a binding, pick an arbitrary instance and pass it to further steps.

Data-loaded gate (hard stop for data-bound containers).

When the target is a SmartTable, SmartList, sap.m.Table, sap.ui.table.Table, SmartChart, or any control whose intent involves binding to rows/items, you MUST confirm row data is loaded before reading the overlay's actionIds. Structural overlays (columns, headers, toolbars) are not evidence of loaded data — they appear before any rows exist.

Evidence required (one of):

  • The user explicitly states data is loaded.
  • You observe row-level overlays in get_overlays (e.g. sap.m.ColumnListItem, sap.ui.table.Row, or overlays whose controlId contains a row index).

If neither is present, do not proceed to action selection. Resolution order:

  1. Prefer the registered page action. If a previous get_page_actions listed loadData (or an equivalent app-contributed action) in registered, call step: "call_page_action" with payload: { id: "loadData" }. Its run() resolves only after rows are loaded; on result.status === "ok", re-run get_overlays and re-check the gate.
  2. Fall back to asking only if no registered loader is available and nothing usable shows up in interactive (e.g. a "Go" button). The original ask — "trigger data loading (click Go, apply a filter, expand a node), then I'll re-run get_overlays" — still applies as a last resort.

Returning needs_user_action from loadData (typically because a mandatory filter hasn't been set) is a hard ask: surface the reason and wait for the user to resolve it before re-attempting.

The gate is unconditional. It applies even when the change feels purely structural (adding a column, reordering, renaming, changing a header label). Do not reason about whether data "matters" for this particular change — if the target is a data-bound container and row-level overlays are absent, stop. The actionIds exposed by an overlay can differ based on data state, and a structurally-correct change against the wrong action variant is exactly the silent failure this skill is built to prevent. "This is just a structural edit, so the gate doesn't apply" is not a valid exception — it is the rationalization the gate exists to block.

Store the chosen controlId and its confidence for the final summary.

Step 5 — Select action (AI decision)

The chosen overlay carries its available action ids in actionIds; the rich per-action metadata (label, description, parameters) for each id lives in the top-level actionsCatalog returned alongside get_overlays. There is no separate get_actions step — read both from the Step 3 response.

Pick an action by id from the RTA Actions — and only if that id is also present in the chosen overlay's actionIds. Never invent an action id. If the user's intent needs an action that isn't in the reference, surface the overlay's available actions and ask the user rather than picking.

Map user intent using the Disambiguation by intent table in the RTA Actions. If the verb doesn't map cleanly (e.g. "tweak the toolbar"), confidence is low — list the actions from actionIds (with their labels from actionsCatalog) and ask.

Confidence gating (thresholds from references/hitl-gating.md):

  • Schema-inspection prerequisite for High band: Before assigning ≥ 0.85, you must have read the candidate's parameters schema (from actionsCatalog[actionId]) and confirmed it matches the kind of operation the user described. If you have not inspected the schema, cap confidence at 0.65 (medium → announce, do not run silently).
  • Same-verb penalty: If two or more candidates share a verb token in their id or label (e.g. multiple ADD_* actions in actionIds), subtract 0.20 from the top candidate's confidence unless the schemas clearly distinguish them.
  • High-band requirement: When proceeding silently, record an Alternatives considered: line stating which other actions were rejected and the schema/semantic reason. If you can't articulate the discriminator, the choice isn't High.
  • If the verb doesn't map cleanly (e.g. "tweak the toolbar"), confidence is low — list the actions from actionIds (with their labels from actionsCatalog) and ask.

Store actionId, the action's parameters schema, and the confidence value.

Step 6 — Get element context

Call step: "get_context", payload { controlId, actionId }. The response is rich and shapes the rest of the workflow:

  • elementType — the chosen control's UI5 class.
  • parentAggregationName — the aggregation slot this control occupies in its parent.
  • actionParameters — the action's parameter schema (same shape as actionsCatalog[actionId].parameters).
  • defaultChildAggregation (optional) — { name, controlType, content: [{ controlId }] } for the control's default aggregation, listing the current direct children by id. Useful for "insert near child X" intents and as a quick sanity check that the control has the children you expect.
  • aggregationsByClass[] — per-class breakdown of every aggregation defined on this control's inheritance chain, with definedIn + libraryName, plus aggregations[].name, controlType, contentLength. Only populated when the action's parameters reference aggregation or selectedElements (the server elides it for actions like rename/remove to keep LLM context small). If you need aggregation info for an action that doesn't take one of those params, the data isn't there — read from defaultChildAggregation or re-derive from the control class.
  • availableModels — the binding environment in effect at this control, keyed by model name. Each entry has modelName, modelClass, defaultBindingMode, contextPath, and contextEntityType (resolved via OData V4 async meta model or V2 sync meta model). Non-OData models with no active binding context on this element are filtered out — they carry no payload-relevant information.
  • actionSpecificContext — whatever the action's own getContext hook returns (action-dependent).

Grounding gate (hard rule). get_context (this step) is not optional whenever the change involves a data binding, an entity, or any property/path. You MUST call it and read its output before Step 8. Every binding path, entity type, entity set, and property name you emit in a payload or in generated fragment/controller content MUST come from get_context (contextEntityType, contextPath, availableModels) or from read_odata_metadata_adp (Step 7) — never from the control's id, the user's phrasing, or a plausible-looking guess. If neither tool gives you the path you need, stop and run Step 7; if Step 7 still doesn't yield it, ask the user (Step 8 required-field rule). Inventing a binding is the single most common cause of "the button renders but the search/data never triggers" — a change that reports success: true yet does nothing. Never skip the tools because a binding "looks obvious."

Use availableModels before reaching for OData metadata

availableModels[<name>].contextEntityType already tells you which entity the control is bound to and contextPath gives you the OData path. For the common "what is this bound to / what's the entity type here" question that Step 7 (OData metadata) used to answer, inspect availableModels first — it short-circuits the metadata call entirely. Only fall through to read_odata_metadata_adp (Step 7) when you need information availableModels can't give you: property-level details, navigation paths, annotation-driven hints, alternative entity sets, or the full EDMX of an unbound area.

Mandatory aggregation/member verification (hard rule — no exceptions)

get_context tells you which aggregations exist (aggregationsByClass[], parentAggregationName, defaultChildAggregation) and which control defines each one (definedIn + libraryName), but not what they're for. Before writing any fragment XML you MUST call lookup_ui5_documentation to verify the aggregation's accepted type and cardinality against the actual deployed UI5 version.

Never skip this call. Type contracts change between UI5 releases — the only safe source is the tool output.

Call lookup_ui5_documentation for every aggregation you plan to use:

lookup_ui5_documentation({
  lookupType: "aggregation",   // or "property" or "event"
  library: "<libraryName from aggregationsByClass>",
  control: "<control FQ name — leaf control is fine; the tool walks the chain>",
  member: "<aggregation / property / event name>",
  appPath: "<adaptation project root>"   // used to discover ui5.yaml version
})

Returns description, type, since, definedIn, inherited, plus lookup-type-specific fields (cardinality for aggregations; defaultValue/group/bindable for properties; parameters for events), and a source block.

Do not write any fragment XML until you have called this tool for every aggregation you plan to use — targetAggregation, every named child aggregation inside the fragment, AND the default aggregation of every non-trivial control you introduce inside the fragment (e.g. a Dialog, SimpleForm, VBox). The scope is all controls in the fragment, not just the outermost placement slot. Three hard rules on the output:

  • Missing: an aggregation not returned does not exist; unknown aggregations are silently discarded while call_action still reports success: true.
  • Cardinality: if the result is 0..1 but you need multiple instances (e.g. per-row content), this aggregation cannot serve that purpose — find the correct multi-instance aggregation on the parent container.
  • No existing children: if the aggregation has no existing children in get_overlays, do not use it as a placement target — it may render hidden or inactive at runtime.

If the accepted type doesn't match, check for a wrapper before seeking an alternative placement. Before using a control from a library not in aggregationsByClass[].libraryName for this session, call the tool against one of its aggregations — a tool error indicating all fetches failed means the library is absent from this runtime.

XML namespace prefix rule (hard rule)

The library field in the tool response is the exact string to use as the XML namespace in the fragment. Never derive the namespace from the control name or from memory — sub-packages look similar to their parent library root but are distinct strings. Always read it from library in the tool output.

Step 7 — Read OData metadata (conditional, only when a data binding is involved)

Run this step only if the user's intention involves binding the element to a data source and availableModels from Step 6 didn't already answer the question. For the simple "which entity is this control bound to" case, availableModels[<name>].contextEntityType is usually enough; reach for the EDMX only when you need richer information (property details, navigation paths, annotations, or entities outside the current binding context).

IMPORTANT Call read_odata_metadata_adp with the adaptation project path to retrieve the metadata (EDMX) of the OData services available to the application. Always use this tool — do not curl, fetch, or grep EDMX from disk. Use the returned entities, properties, navigation paths, key fields, and annotations as context to decide:

  • Which entity set / entity type to bind against
  • The exact property name and path (including any navigation traversal)
  • Whether the property is suitable for the target control (type, nullability, length)
  • Any annotation-driven formatting hints that should be applied

Typical triggers:

  • Binding a control property to an OData field (e.g. text="{Customer/Name}")
  • Adding a bound text/value/description/title to a control
  • Binding a table column or list item to an entity property
  • Wiring a new control, fragment, or section to a backing entity set, navigation property, or function import
  • A controller handler will read one or more model properties at runtime (e.g. to build a URL, compute a value, or populate a dialog)

If the change is purely structural or behavioral (static labels, visibility toggles, controller-only logic, etc.) and does not reference any backing data, skip this step.

Feed these decisions into Step 8 (payload preparation) and into the fragment XML / controller extension content generated in Step 12. If the metadata does not contain a property matching the user's request, stop and ask — do not invent a binding path.

Step 8 — Prepare action payload (AI decision)

Build actionPayload from the action's parameters schema (Step 5), the element context (Step 6), and the user's instructions. Use the exact field names from the RTA Actions — fragmentPath (not fragmentName), codeRef, viewId, etc.

For CTX_ADDXML:

  • fragmentPath: fragments/<Name>.fragment.xml — pick <Name> from the user's intent (e.g. OrderDetailsButton). The fragment file itself is created in Step 12.
  • targetAggregation: from get_context. Always call lookup_ui5_documentation (see Step 6) to confirm the aggregation name exists on the control, its accepted controlType, and its cardinality before finalising the payload — getting this wrong inserts the fragment into the wrong slot and call_action will still report success: true.
  • index: 0 for "at the beginning"; for "append at end" use the current child count, which is aggregationsByClass[<class with the aggregation>].aggregations[<aggregation name>].contentLength from the Step 6 response (fall back to defaultChildAggregation.content.length when the aggregation is the default and aggregationsByClass wasn't populated). Ask if the user said "after the X" and the position isn't determinable from context.

For CTX_EXTEND_CONTROLLER:

  • codeRef: coding/<Name>.js — <Name> typically matches the fragment's controller name (e.g. OrderDetailsExt). The JS file itself is created in Step 12.
  • viewId: the controlId of the current selection works; otherwise the view id from get_context.
  • instanceSpecific: omit unless the user explicitly asked to scope to one instance.

General rules:

  • Fill structural fields from get_context; fill value fields from instructions.
  • Binding provenance (hard rule): any binding path, entity type, entity set, or property name in this payload (and in the Step 12 fragment/controller content) must trace to a specific field of the Step 6 get_context response or the Step 7 EDMX. If you cannot point to where a path came from, you are inventing it — stop, run Step 7, and if it still isn't there, ask. See the Grounding gate in Step 6.
  • Runtime property availability check (hard rule): whenever a controller handler will read model properties at runtime (e.g. getProperty, getObject, or any expression binding), call read_odata_metadata_adp (Step 7) and derive the effective $select from the UI annotations on the bound entity type. Only properties provably included in that annotation-driven set may be read synchronously. Every other property — including annotation companions (sap:unit, sap:text, sap:scale, etc.) — must be fetched on demand with an explicit $select. When the handler constructs any computed output from the properties (URL, concatenated string, arithmetic), always fetch regardless of annotation membership — a silent undefined produces no error at call_action time and is only discoverable at runtime. Dropping the property from the handler is never an acceptable alternative — if the user's intent requires it, fetch it. The safe patterns are:
    • OData V2: oModel.read(oContext.getPath(), { urlParameters: { "$select": "PropA,PropB" }, success: function(oData) { … } })
    • OData V4: oContext.requestProperty(["PropA", "PropB"]).then(function([vA, vB]) { … })
  • Existing change awareness: before finalising any payload or generated code, review the existing changes in the project (imported key user changes and any developer changes already in webapp/changes/) for related intent. When an existing change addresses something similar to the current requirement, align the new output with it — reuse the same property names, URL patterns, entity paths, and logic rather than re-deriving them independently. Silently diverging from an established pattern in the same project is a defect.
  • Validate types match the schema (string vs int vs boolean — index is int, not string).

Confidence gating (thresholds from references/hitl-gating.md — strictest of the three because a successful call_action with a wrong payload is the worst silent failure):

  • Per-field confidence: use the rubric. Whole-payload confidence is the minimum of the per-field values.
  • Required-field rule: see Confidence & HITL Gating — a required field with no derivable value caps whole-payload confidence at 0.55 (ask band).
  • High → submit the payload silently.
  • Medium → announce the payload: Action <actionId> with payload <JSON> (confidence 0.7x). Continuing — interrupt to change. Continue.
  • Low → present the payload as a draft and ask for confirmation or corrections before calling.

Store the payload + confidence for the final summary.

Step 9 — Execute action

Call step: "call_action", payload { controlId, actionId, actionPayload }. On success: true, continue. On error, report and offer to retry with adjusted parameters.

Step 10 — Loop for multiple changes

If the user requested multiple changes, repeat Steps 3–9 only (never Steps 1–2, never a fresh start) once per change, all under the same site+frameId. The UI may have changed, so re-run get_overlays between changes — and re-run get_page_actions if a fresh navigation is needed. A single change request can still require multiple operations and changes to be created. If a single request implies multiple operations (e.g. "add a button that calls a function" = fragment + controller extension), execute each as a separate iteration.

Create all changes before saving.

Step 11 — Save

Call step: "save". Returns { saved: true } on success.

Step 12 — Generate fragment and controller extension content

After saving, use adp_controller_extension to fill in the content for any fragments and controller extensions that were created.

Phase 1 — knowledge base. Call with:

  • appPath: adaptation project path
  • prompt: describe the functionality (from user instructions)
  • (do not pass aiResponse)

This returns project context, layer info, namespace rules, and existing files.

Phase 2 — write content. Generate controller extension and fragment XML using the Phase 1 knowledge base, then call again with:

  • appPath: same path
  • prompt: same prompt
  • aiResponse: your generated code with **Path:** markers
  • controllerName: the controller extension name

Format:

**Path:** webapp/changes/coding/MyExtension.js
```javascript
// controller extension code

Path: webapp/changes/fragments/MyFragment.fragment.xml

<!-- fragment code -->

Include XML comments inside fragments for context hints:
```xml
<!-- viewName: <from context> -->
<!-- controlType: <from context> -->
<!-- targetAggregation: <from context> -->

Step 13 — Validate

Validate before stopping (hard rule). After generating files (Step 12), you MUST call restart before stop. Fragment and controller extension controls only appear in get_overlays after the editor reloads with the written files on disk. stop must never immediately follow file generation — the step between them is always restart + overlay verification. Skipping this step means the change is unverified; calling stop first makes recovery impossible within the session.

After generating all files, call restart to reload the current editor browser with the newly written fragment and controller extension files.

run_rta_workflow_step { step: "restart", site, frameId }
→ { site, frameId, rtaStarted: true }

Store the returned site and frameId. Navigate back to the editing target (repeat Step 2 as needed) and call get_overlays. Every control inserted via CTX_ADDXML must appear as an overlay — this is the confirmation that the fragment loaded correctly at runtime.

Child overlay rule (hard rule). For each control you added via CTX_ADDXML, you must find an overlay whose controlId matches that control's own id — not its parent's. The parent aggregation container appearing in get_overlays is not proof that the inserted child was accepted. If the parent is present but no overlay for the new control's id exists, the runtime silently rejected the fragment content (the change file was written and call_action returned success: true, but the control never rendered). This is a distinct failure state from "fragment not found."

Absent child overlay → diagnose immediately:

  1. Check the wrapper element type used in the fragment. SAPUI5 aggregations enforce type contracts: e.g. SmartForm.groupElements requires children that implement IFormGroupElement (sap.ui.comp.smartform.GroupElement qualifies; sap.ui.layout.HorizontalLayout does not). A wrong wrapper is silently dropped with no error.
  2. Call lookup_ui5_documentation (see Step 6) for the target aggregation and compare its accepted controlType against what your fragment root element actually is.
  3. Replace the wrapper with the correct SAPUI5 type, write the corrected fragment file, call restart, re-navigate, and call get_overlays again.
  4. Repeat until the new control's own overlay entry is present.

If an expected control is missing from the overlay list for other reasons (wrong fragmentPath, malformed XML, namespace mismatch): inspect the relevant change file and fragment XML, fix the file, call restart again with the same site+frameId, re-navigate, and call get_overlays again. Repeat until all inserted controls are confirmed present.

Step 14 — Cleanup

Call step: "stop". The server closes the session; if it was the last one, the browser shuts down too.

Then kill the editor server. open_adaptation_editor already returns ready-made kill instructions for the host platform — relay those. The manual forms, by platform:

Mac/Linux:

kill -9 $(lsof -ti:<port>)   # by port (recommended)
kill <processId>             # by PID

Windows:

for /f "tokens=5" %a in ('netstat -ano ^| findstr :<port>') do taskkill /PID %a /F   :: by port
taskkill /PID <processId> /F                                                          :: by PID

Report to the user: summary of all changes made, files created, any issues encountered, plus the confidence the model assigned to each AI decision (control selection, action selection, payload prep) for every change — this makes silent high-confidence decisions auditable after the fact.

Error Handling

Situation Action
Page not loading Wait 30 s. If still nothing, verify URL and editor server is running.
start returns rtaStarted: false Retry once after 3 s. If still false, the app may not support RTA.
get_overlays returns empty Wait 5 s, retry. If still empty, ask the user to confirm the editor is on the right view.
Expected action id is not in the chosen overlay's actionIds Stop. This is the hard-stop case from Confidence & HITL Gating. Do not silently switch controls or actions. Tell the user what you expected, what came back, and ask how to proceed.
Action execution fails Report error, offer retry with different params.
Save fails Report error. Inform user changes may be lost.
adp_controller_extension Phase 1 (knowledge base) fails Surface the error and stop. Ask the user to verify appPath points to an adaptation project root (a folder containing webapp/manifest.appdescr_variant).
Unknown site or missing site field Pass the site URL from open_adaptation_editor to every step.
Frontend action ... not registered The editor hasn't finished loading, or wrong frame. Verify frameId: "preview" and retry.
Executable doesn't exist at .../chromium-... or browserType.launch: ... referencing a missing browser No system Chrome and no Playwright Chromium installed. (1) Prompt the user to run npx playwright install chromium (or run it on their behalf if they consent). (2) Retry start with the same payload. (3) If still failing, ask the user to set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH to a known Chrome/Chromium binary.

Multi-Change Strategy

When the user requests multiple changes:

  1. Parse all intended changes upfront.
  2. Execute Steps 3–9 once per change, all under the same site+frameId.
  3. Save once at the end (Step 11).
  4. If one change fails, save the successful ones and report which failed.
  5. Generate content for all fragments / extensions together in Step 12.
  6. Stop the session (Step 14) only after everything is done.

Example Session

Workflow example (button + dialog on an Object Page): references/example-session.md.