abap2UI5 protocol

The written, versioned contract between abap2UI5 frontends and backends - with JSON Schemas and conformance suites, so either side can be swapped.

abap2UI5 is server-driven UI ("UI5 over the wire"): the browser frontend sends one JSON roundtrip per user event - the event, the model delta, the draft id - and the backend runs the app's main( ) and answers with views, the model, messages and frontend actions. That protocol is spoken today by three backends (abap2UI5 on an ABAP system, the same framework transpiled to Node as @abap2ui5/node-runtime, cap2UI5 on CAP) and three frontends (the UI5 SPA, the MCP server's agent client, the ABAP frontend simulator). This repository writes it down.

The layers

 profiles/   view profiles - what is inside a view string
   ui5        full UI5 XML + the .eB/.eF wire forms + the boot page   (the UI5 SPA)
   portable   a 61-control subset every renderer renders              (Web Components, native, ...)
   semantic   agent snapshot v1 - the screen as data                  (agents, test drivers)
 ---------------------------------------------------------------------------------
 spec/       the core protocol - mandatory for every frontend and backend
   transport  one endpoint, GET page / POST roundtrip, headers, CSRF, HEAD, sap-contextid
   request    S_FRONT, events and their arguments, the model delta (__delta), CONFIG
   response   S_FRONT, T_SYSTEM / T_CUSTOM, the five view slots, MODEL, processing order
   actions    follow-up actions, messages
   sessions   drafts, draft ids as snapshots, expiry, failed roundtrips
   navigation app start resolution, app stack, routes, app-state hash, ROUTER action
   errors     the 500 text body and what a frontend does with it
   versioning PROTOCOL 2, compatible changes
 schema/     JSON Schemas (2020-12): request, response, snapshot, portable profile
 conformance/
   backend    the backend suite - plays the frontend over HTTP     (implemented)
   frontend   the frontend suite - plays the backend, adapters for (implemented)
              the UI5 SPA (Playwright), the agent client, the
              Web Components frontend, the Adaptive Cards and the
              terminal renderer
   apps       the conformance apps: ABAP classes + cap2UI5 twins
   hosts      the two reference backends, started with the apps deployed
 renderers/
   adaptive-cards  a portable renderer without a browser: response -> Adaptive
              Card 1.5, Action.Submit -> request                    (prototype)
   terminal   an abap2UI5 app in a terminal: keys in, text screen out,
              the CLI abap2ui5-tui (node runtime, cap2UI5, SAP systems)
   common     what both renderers share: view helpers, payload -> request
 traffic/    real traffic of both reference backends and three frontends

Start with spec/core.md. Every normative statement cites the source file and method it was derived from (spec/README.md).

Status

• Protocol 2, specification revision 0.3, derived from abap2UI5 1.146.0 (commit b812079); the maintainer decided the ten open questions (spec/open-questions.md).
• Backend suite: 76 checks (62 MUST, 14 SHOULD; 69 core, 7 UI5 profile). Both reference backends pass every check but error.no-reflection, new in revision 0.3 (the request URL reflected into the 500 body; fixed in abap2UI5 core, pinned until the runtime release carries it) - node-runtime 75/76, cap2ui5 74/76 with one SHOULD warning (conformance/RESULTS.md).
• Schemas validate all 336 recorded requests, 320 responses and 18 agent snapshots, checked by the shipped validator and by ajv.
• Portable profile v1 filled from a census of 247 core apps (73.7 % by controls, 64.8 % run unchanged).
• Frontend suite: 81 checks (66 MUST, 15 SHOULD; 66 core, 8 portable, 4 UI5, 3 semantic), scripted from the recorded traffic. The official UI5 SPA passes every MUST but one - message box details stay empty on OpenUI5

  = 1.120 (fix under way); the agent client (mcp-server a4d9f07), the Adaptive Cards renderer and the terminal renderer pass every check that applies to them (61, 66 and 72 - the terminal's include the router checks); the Web Components frontend 68 of 68, with one intermittent failure (conformance/RESULTS.md).

• Adaptive Cards renderer (prototype, renderers/adaptive-cards/): all 65 portable controls mapped onto Adaptive Cards 1.5, the way back from an Action.Submit to the next request, golden cards of recorded traffic.
• Terminal renderer (renderers/terminal/): an abap2UI5 app in a terminal - npx abap2ui5-tui <url> --app <CLASS> against the node runtime, cap2UI5 or an SAP system (basic auth, cookies, CSRF, sap-contextid), all 65 portable controls as keyboard-driven widgets, a hash history so Back works, --print for logs, CI and screen readers; pure Node, no dependencies.
• Not yet run against an ABAP system.

Run the backend suite

npm ci

# against any backend that serves the conformance apps
npx abap2ui5-conformance backend --url http://localhost:3000/ --profile ui5

# against the reference backends
npm run conformance:node-runtime        # transpiles the ABAP apps, serves, runs
npm ci --prefix conformance/hosts/cap2ui5
npm run conformance:cap2ui5

To test your backend: deploy the conformance apps (abapGit for ABAP; the JS twins for cap2UI5), point --url at the endpoint. Options, the library API and the check list: conformance/backend/README.md.

Run the frontend suite

npx abap2ui5-conformance frontend --adapter ui5      # the UI5 SPA (ABAP2UI5_HOME=<abap2UI5 checkout>) in Chromium
npx abap2ui5-conformance frontend --adapter agent    # the agent client of abap2UI5/mcp-server
npx abap2ui5-conformance frontend --adapter adaptive-cards   # the Adaptive Cards renderer of this package
npx abap2ui5-conformance frontend --adapter terminal         # the terminal renderer of this package

Run an app in the terminal

npm run serve:node-runtime &                     # the conformance apps on http://localhost:3000/
npx abap2ui5-tui http://localhost:3000/ --app Z2UI5_CL_CONF_BIND
npx abap2ui5-tui "https://host/sap/bc/z2ui5?sap-client=100" --app Z2UI5_CL_MY_APP --user ME --print

Keys, options and the control mapping: renderers/terminal/README.md.

Adapters, options and the check list: conformance/frontend/README.md.

Develop

npm test                 # schemas, traffic, docs, portable profile, CLI, both backends,
                         # the frontend suite (agent client, Adaptive Cards and terminal
                         # renderer; UI5 SPA with a checkout + Chromium), the golden
                         # cards and screens, the terminal against the node runtime
                         # (PROTOCOL_SKIP_BACKENDS=1 / PROTOCOL_SKIP_BROWSER=1 skip the slow parts)
npm run record           # re-record traffic/ from both backends
npm run lint:abap        # abaplint over the ABAP conformance apps
npm run generate         # regenerate the check lists, the portable-profile sections and
                         # the Adaptive Cards and terminal mapping tables
npm run demo:adaptive-cards -- slots.popup-destroy 0 1   # a recorded response as card JSON

Node 22 or later. The package has no runtime dependencies; the dev dependencies are the reference backend (@abap2ui5/node-runtime, the transpiler, express), abaplint, ajv, and for the UI5 adapter playwright-core and the @openui5/sap.m source packages (UI5 without a CDN).

Related

abap2UI5 (backend + UI5 frontend) · cap2UI5 · mcp-server (agent client, snapshot implementation) · headless-frontend · linter

License

MIT