Idea Summary
Add a native Dynamic Action (DA) to APEX that invokes an Ajax Callback and awaits its Promise before continuing. The DA should let developers map inputs (items/session values) to the request, await the response, and consume iteither in JavaScript (as an object) or by writing back to PL/SQL/session state—all declaratively, without custom wrappers. This closes a common gap currently solved with custom JS or third‑party plugins.
Problem
- Today, calling
apex.server.process/Ajax callbacks from a DA often requires custom JavaScript, manual Promise/thenhandling, and ad‑hoc error/timeout logic.
- Chaining DA steps that depend on the response (e.g., populate items, conditionally refresh regions) is cumbersomeand error‑prone.
- There is no declarative contract for payload → PL/SQL and PL/SQL → response (JSON), nor built‑in retry/backoff, debounce, cancel previous, or instrumentation.
Objectives
- Provide a first‑class DA action to invoke an Ajax callback and await completion.
- Enable declarative request/response mapping (items ↔ JSON ↔ PL/SQL record).
- Support error handling, timeout, debounce/throttle, cancel previous, and retry with backoff.
- Expose response to subsequent DA steps and to client code (JS), and allow server write‑backs (session state/items).
- Deliver telemetry and consistent security (CSRF, allowlist of processes).
Use Case
- Populate Items and Refresh Region: User selects an order, DA calls Ajax process to fetch summary, waits for response, populates customer/total items, and refreshes a region only if
success=true.
- Client‑side Logic: Ajax response includes a directive (
nextStep=CONFIRM), consumed in a subsequent JS DA step that shows a confirmation dialog.
- Search‑as‑You‑Type: Text field invokes Ajax callback with debounce (300ms) and cancel‑previous enabled, preventing request pile‑ups.
- Error Recovery: Ajax callback fails due to network; DA retries with backoff, shows declarative error message if all attempts fail.
Preferred Solution (Optional)
Goal: Provide a native, promise-first DA to invoke Ajax callbacks with declarative mapping, robust flow control, and built-in observability/security.
Core Decisions
- Action Name: Invoke Ajax Callback.
- Promise-first: DA execution awaits completion; exposes
this.response / apex.da.response() to subsequent steps.
- Declarative mapping: Items/JSON/PLSQL record mapping both ways; optional write-back to session state.
- Flow controls: Cancel previous, debounce/throttle, timeout, retry with backoff, and error hooks.
- Branching: JSONPath evaluation to drive True/False branches and conditional refresh.
- Security: Allowlist of processes/sources, CSRF handled, optional HMAC payload signature.
- Telemetry: Counts, p95 latency, bytes, retries/cancellations; Dev Toolbar mini-log.
- UX: Tabs for Request, Await/Flow, Response, Errors/Retry, Security, Telemetry; test console.
- Compatibility: Opt-in; built over
apex.server.process, no breaking changes.