Appearance
UI Templates (/ui-templates)
A UI template is a stored OpenUI program: a dashboard, or the layout of a page area. The admin webapp opens it in a slot (for example the home page, core:home). A user saves their own templates. An administrator shares templates with roles or with everyone and picks the template that opens by itself.
- API:
service/api/src/routes/ui-templates.ts,services/ui-templates.ts(UiTemplatesService), migration104-create-ui-templates.ts. Tablesodp_ui_templatesandodp_ui_templates_roles. - Webapp BFF:
apps/webapp/server/src/repositories/ui-templates/forwards/api/ui-templates*to the same routes, with the user's own token. The client calls/api/ui-templates…; this page shows the API paths (/ui-templates…). - Home dashboard UI:
docs/webapp/dev/dashboard.md.
odp_ui_templates is a system table: /items/odp_ui_templates refuses it. Every write goes through UiTemplatesService, also from a version promote or an extension.
Routes
Every route needs a signed-in user. A request without a user gets 403 FORBIDDEN.
| Method | Path | Body | Response |
|---|---|---|---|
GET | /ui-templates | — | { data: Template[], meta? } |
GET | /ui-templates/default?slot=…&context_key=… | — | { data: Template | null, source } |
GET | /ui-templates/:id | — | { data: Template } |
POST | /ui-templates | TemplateInput | { data: Template } (the row as stored) |
PATCH | /ui-templates/:id | Partial<TemplateInput> | { data: Template } |
DELETE | /ui-templates/:id | — | 204, no body |
GET /ui-templates and GET /ui-templates/:id take the usual query parameters: fields, filter, sort, limit, offset, page, search, meta (see Items CRUD & Query System).
Payload
Template (response)
| Field | Type | Set by | Notes |
|---|---|---|---|
id | uuid | server | Always generated. A client id is dropped. |
title | string, 1–255 | client | Required on create. |
content | string | client | The OpenUI program text. Required on create. No size limit. |
slot | string, ≤ 255 | client | Required on create. Form namespace:name or namespace:page:slot, see Slot and context_key. |
context_key | string, ≤ 255 | client | '' (default) or an existing collection name. |
scope | personal | role | global | client | Default personal. Only an admin sends another value. |
is_default | boolean | client | Default false. See Defaults. |
share_roles | uuid[] | client (admin) | Role ids of a role template. Returned to an admin only. Not stored on the row. |
webapp_version | string | null | client | Diagnostics only. See Versions. |
module_version | string | null | client | Diagnostics only. |
source_turn_id | string | null, ≤ 255 | client | The assistant turn that made the program, when there is one. |
source_model | string | null, ≤ 255 | client | The model that made the program, when there is one. |
user_created | uuid | null | server | The creator. Set on create, never changes. null once that user is deleted. |
user_updated | uuid | null | server | The last writer. Set on create (= user_created) and on every update. |
date_created | ISO-8601 timestamp | server | |
date_updated | ISO-8601 timestamp | server | Set on create and on every update. |
author | { id, name } | null | server | Read only, from user_created. null = the user is deleted. |
editor | { id, name } | null | server | Read only, from user_updated. Equals author until the first update by someone else. |
name is first_name and last_name joined by a space (empty string when the user has neither).
The server drops a client value for id, user_created, user_updated, date_created, date_updated, author and editor. It does not refuse the request.
fields may name author, editor and share_roles. The service reads the columns they come from.
TemplateInput (request)
title, content, slot, context_key, scope, is_default, share_roles, webapp_version, module_version, source_turn_id, source_model. The body must be a JSON object.
- Create:
title,contentandslotare required, non-empty strings. - Update: a field that is present must be valid;
title,contentandslotmust stay non-empty. share_roles: a list of existing role ids, ornull(same as[]). A non-empty list needsscope: 'role'. Each write sends the full list: it replaces the stored set. When the scope changes away fromrole, the server removes every role link.
Slot and context_key
slotnames where the template opens:namespace:name, ornamespace:page:slotfor an area of a module page; lower-case letters, digits and-in each part (^[a-z0-9-]+:[a-z0-9-]+(:[a-z0-9-]+)?$). The home page iscore:home; the workflow inbox area isworkflow:inbox:top. A module uses its own namespace. Slots are compared as whole strings.context_keynarrows a slot to one collection:''for a slot that has no collection, or the name of an existing collection (for example a dashboard shown on thearticleslist). Any other value is400.
Defaults
is_default marks the template that opens by itself:
- on a
personalrow: "my template" for that slot and context; - on a
roleorglobalrow: the default an administrator sets for those viewers.
The service keeps at most one default per group. Setting a new one clears the old one, in the same transaction. A group is the same slot and context_key, and:
personal: the same owner;role: a shared role in common;global: every global row.
Lookup order (GET /ui-templates/default)
slot is required. context_key defaults to ''.
- The caller's own
personaldefault. - The default of a
roletemplate shared with the caller's primary role. - The
globaldefault. - Nothing:
{ "data": null, "source": null }. The client then shows its built-in program.
This holds for every slot. A shared template that is not the default shows only in a template list.
Ties in one step: the latest date_updated wins, then the higher id. Every candidate goes through the caller's read access. source is 'personal', 'role', 'global' or null.
webapp_version and module_version
Both are for diagnostics: the server stores them and never acts on them.
- Form: 1–64 characters from
0-9 A-Z a-z . + -, ornull. Anything else is400. webapp_version: the version of the webapp that saved the template.module_version: the version that the slot's module declares at the last save. A slot of a core module (such ascore:home) sendsnull.
Send both on every create and on every update, so they describe the last save.
Who may do what
Administrator
An administrator reads, writes and deletes every row. Only an administrator:
- sends
scopeother thanpersonal; - sends
share_roles; - sets
is_defaulton aroleorglobalrow.
Anyone else gets 403 FORBIDDEN ("Only an administrator shares a template or sets a shared default"), whatever the policies say.
An administrator reads every row, the personal rows of other users included. To list the admin's own templates plus the shared ones, filter { "_or": [{ "user_created": { "_eq": "<admin id>" } }, { "scope": { "_neq": "personal" } }] } with the real id (the client does not resolve $CURRENT_USER).
Non-admin (app access)
The app-access grant gives every app user:
| Action | Rows | Fields |
|---|---|---|
| read | own rows; role rows shared with the caller's primary role; global rows | every field except share_roles |
| create | scope: 'personal', user_created = the caller | every input field |
| update | own personal rows | every input field; scope must stay personal |
| delete | own personal rows | — |
A non-admin may set is_default on their own personal row. They may also copy a shared template: POST its title and content as a new personal row. A filter on user_created with the caller's own id works and returns their own rows. A policy can give a role more than this grant, but the admin-only rules above still hold.
Errors
The body is { "errors": [{ "message": "...", "extensions": { "code": "..." } }] }.
| Status | Code | When |
|---|---|---|
| 400 | INVALID_PAYLOAD | the body is not an object; title / content / slot missing or empty; slot not namespace:name or namespace:page:slot; scope unknown; context_key not '' or an existing collection; is_default not a boolean; a version field of the wrong form; share_roles not a list of ids, holds an unknown role id, or is sent without scope: 'role'; GET /default without slot |
| 403 | FORBIDDEN | no signed-in user; a share or a shared default by a non-admin; a row the caller may not read, update or delete (a missing id answers the same, so ids cannot be probed) |
Caps
No limit on content, and no limit on the number of templates per user. Column limits: title, slot, context_key, source_turn_id, source_model 255 characters; version fields 64 characters.
Examples
List the templates of a slot, newest first:
http
GET /ui-templates?filter[slot][_eq]=core:home&sort=-date_updated&fields=id,title,scope,is_default,author,editor&meta=filter_countjson
{
"data": [
{ "id": "0b5e…", "title": "Sales overview", "scope": "global", "is_default": true,
"author": { "id": "7f1c…", "name": "Ada Admin" }, "editor": { "id": "7f1c…", "name": "Ada Admin" } }
],
"meta": { "filter_count": 1 }
}Open the template that opens by itself on the home page:
http
GET /ui-templates/default?slot=core:homejson
{ "data": { "id": "0b5e…", "title": "Sales overview", "slot": "core:home", "context_key": "", "scope": "global", "is_default": true, "…": "…" }, "source": "global" }Read one template:
http
GET /ui-templates/0b5e…?fields=id,title,content,authorjson
{ "data": { "id": "0b5e…", "title": "Sales overview", "content": "root = Stack([…])", "author": { "id": "7f1c…", "name": "Ada Admin" } } }Save my own template and make it my home page:
http
POST /ui-templates
Content-Type: application/json
{ "title": "My home", "content": "root = Stack([…])", "slot": "core:home", "is_default": true,
"webapp_version": "0.25.0", "module_version": null }json
{ "data": { "id": "c2d9…", "title": "My home", "scope": "personal", "is_default": true,
"user_created": "a41e…", "user_updated": "a41e…", "date_created": "2026-11-03T09:12:00.000Z",
"date_updated": "2026-11-03T09:12:00.000Z", "author": { "id": "a41e…", "name": "Bao User" },
"editor": { "id": "a41e…", "name": "Bao User" }, "…": "…" } }Share a template with two roles and make it their home default (admin):
http
PATCH /ui-templates/0b5e…
Content-Type: application/json
{ "scope": "role", "share_roles": ["3a0f…", "9d27…"], "is_default": true }json
{ "data": { "id": "0b5e…", "scope": "role", "is_default": true, "share_roles": ["3a0f…", "9d27…"], "…": "…" } }Delete:
http
DELETE /ui-templates/c2d9…204 No Content.
Client render rules
The API stores content as text and never runs it. The webapp client runs it, under these rules (apps/webapp/client/src/genui/, modules/genui/):
- Values and images. Before a value reaches a display, the client checks it with
isSafeDisplayValue(url-safety.ts). First, tab, CR and LF are removed and leading control characters and spaces are trimmed, as a browser does. A string must then not be able to become a URL: no scheme (note:xcounts,Note: xis prose), no embeddedx://, no network path//, no leading/or\, no..segment, no icon outside Phosphor (i-ph-…). Every check runs on each percent-decoded layer (at most 5 layers; deeper text is refused). Objects and arrays are checked to depth 8, object keys as text too; anidmust be a plain id. An image source passesisSafeImageSourcewhen it is an inlinedata:image/…(as is), or one of this app's asset routes (/api/assets/:id,/assets/:id, with an optional?or#part) with no..segment in any decoded layer. - No partial render. The stored home dashboard (
use-home-dashboard.ts,dashboardsurface) runsruntime.validatefirst. When it fails (a component that no longer exists, noroot, a name used but not defined), the client draws its default program and a warning, never part of the saved program. Every viewer sees the warning; the owner also sees the errors (up to 3 messages). A tool that is not found (tool-not-found) does not count:Query()needs the agent registry, and with the agent off it reports the error at that node. A chatui.presentis checked by the tool before it shows, and its errors go back to the model. - Refresh floor. The refresh interval of
Query()(4th argument, seconds) has a floor of 15 s, applied inGenUiViewbefore the renderer, on every surface, to calls named exactlyQuery. A number of 0 or less stays (no auto refresh). A smaller number becomes 15 s, and so does an expression, whose value is known only at run time. Separately, the tool provider runs at most one call per tool and arguments, per viewer, every 15 s. - Viewer's rights. A shared program runs its reads (widgets and
Query()) under the rights of the user who views it, not of its author. Values typed into the program itself (text, numbers, a hand-made table) are not filtered: every viewer sees them. So before an admin shares, the share dialog lists the typed values, the data sources and the links, and Save stays disabled until the admin ticks the confirmation.