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_stepis 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-serverrunning as an MCP server. It providesrun_rta_workflow_stepand the otherfiori-mcptools 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:
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATHenv var (absolute path to a Chromium binary)PLAYWRIGHT_BROWSER_CHANNELenv var (chrome,msedge,chrome-beta, etc.)- System Google Chrome (default channel)
- 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,notedescribes 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-checkget_page_actions/get_overlaysif you expected a context change. - On
call_page_action,needs_user_actioncovers two cases: (a) the action's ownrun()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 intoneeds_user_actionwith the error message asreason. The two are indistinguishable from the surface — ifreasonreads 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. Useget_page_actions/call_page_action/press_interactiveto 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), andstop(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, andsave(Step 11) once at the end. Never re-enter Step 1 (start) per change — a freshstart/stopper 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 inregisteredfits.
Decision order (always prefer registered over interactive):
- 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 →loadDatathennavigateToRow), callstep: "call_page_action"withpayload: { id }. The action'srun()resolves only when the page has settled (table loaded, OP rendered). - Handle
needs_user_action. Ifresult.status === "needs_user_action", surfaceresult.reasonto 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 callget_page_actionsagain. - Fall through to
interactiveonly when no registered action fits. Pick the entry whoselabelandkindmatch the user's words and callstep: "press_interactive"withpayload: { controlId }. The press uses a real user-gesture click and waits best-effort for the page to change. - Loop. After each
call_page_action/press_interactive, callget_page_actionsagain. Theregisteredset is the live signal that you've moved to a new context — e.g.navigateToSectionappearing 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
TitleorHeaderincontrolType - "the table" →
sap.ui.table.Tableorsap.m.Table - "button X" →
sap.m.Buttonwith matching label - "toolbar" →
sap.m.Toolbarorsap.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 whosecontrolIdcontains a row index).
If neither is present, do not proceed to action selection. Resolution order:
- Prefer the registered page action. If a previous
get_page_actionslistedloadData(or an equivalent app-contributed action) inregistered, callstep: "call_page_action"withpayload: { id: "loadData" }. Itsrun()resolves only after rows are loaded; onresult.status === "ok", re-runget_overlaysand re-check the gate. - 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-runget_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
parametersschema (fromactionsCatalog[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 inactionIds), 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 fromactionsCatalog) 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 asactionsCatalog[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, withdefinedIn+libraryName, plusaggregations[].name,controlType,contentLength. Only populated when the action's parameters referenceaggregationorselectedElements(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 fromdefaultChildAggregationor re-derive from the control class.availableModels— the binding environment in effect at this control, keyed by model name. Each entry hasmodelName,modelClass,defaultBindingMode,contextPath, andcontextEntityType(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 owngetContexthook 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 fromget_context(contextEntityType,contextPath,availableModels) or fromread_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 reportssuccess: trueyet 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_actionstill reportssuccess: true. - Cardinality: if the result is
0..1but 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: fromget_context. Always calllookup_ui5_documentation(see Step 6) to confirm the aggregation name exists on the control, its acceptedcontrolType, and its cardinality before finalising the payload — getting this wrong inserts the fragment into the wrong slot andcall_actionwill still reportsuccess: true.index:0for "at the beginning"; for "append at end" use the current child count, which isaggregationsByClass[<class with the aggregation>].aggregations[<aggregation name>].contentLengthfrom the Step 6 response (fall back todefaultChildAggregation.content.lengthwhen the aggregation is the default andaggregationsByClasswasn'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: thecontrolIdof the current selection works; otherwise the view id fromget_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_contextresponse 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), callread_odata_metadata_adp(Step 7) and derive the effective$selectfrom 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 silentundefinedproduces no error atcall_actiontime 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]) { … })
- OData V2:
- 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 —
indexis 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 pathprompt: 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 pathprompt: same promptaiResponse: your generated code with**Path:**markerscontrollerName: 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
restartbeforestop. Fragment and controller extension controls only appear inget_overlaysafter the editor reloads with the written files on disk.stopmust never immediately follow file generation — the step between them is alwaysrestart+ overlay verification. Skipping this step means the change is unverified; callingstopfirst 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:
- Check the wrapper element type used in the fragment. SAPUI5 aggregations enforce type contracts: e.g.
SmartForm.groupElementsrequires children that implementIFormGroupElement(sap.ui.comp.smartform.GroupElementqualifies;sap.ui.layout.HorizontalLayoutdoes not). A wrong wrapper is silently dropped with no error. - Call
lookup_ui5_documentation(see Step 6) for the target aggregation and compare its acceptedcontrolTypeagainst what your fragment root element actually is. - Replace the wrapper with the correct SAPUI5 type, write the corrected fragment file, call
restart, re-navigate, and callget_overlaysagain. - 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:
- Parse all intended changes upfront.
- Execute Steps 3–9 once per change, all under the same
site+frameId. - Save once at the end (Step 11).
- If one change fails, save the successful ones and report which failed.
- Generate content for all fragments / extensions together in Step 12.
- Stop the session (Step 14) only after everything is done.
Example Session
Workflow example (button + dialog on an Object Page): references/example-session.md.