Skip to content

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), migration 104-create-ui-templates.ts. Tables odp_ui_templates and odp_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.

MethodPathBodyResponse
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-templatesTemplateInput{ data: Template } (the row as stored)
PATCH/ui-templates/:idPartial<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) ​

FieldTypeSet byNotes
iduuidserverAlways generated. A client id is dropped.
titlestring, 1–255clientRequired on create.
contentstringclientThe OpenUI program text. Required on create. No size limit.
slotstring, ≤ 255clientRequired on create. Form namespace:name or namespace:page:slot, see Slot and context_key.
context_keystring, ≤ 255client'' (default) or an existing collection name.
scopepersonal | role | globalclientDefault personal. Only an admin sends another value.
is_defaultbooleanclientDefault false. See Defaults.
share_rolesuuid[]client (admin)Role ids of a role template. Returned to an admin only. Not stored on the row.
webapp_versionstring | nullclientDiagnostics only. See Versions.
module_versionstring | nullclientDiagnostics only.
source_turn_idstring | null, ≤ 255clientThe assistant turn that made the program, when there is one.
source_modelstring | null, ≤ 255clientThe model that made the program, when there is one.
user_createduuid | nullserverThe creator. Set on create, never changes. null once that user is deleted.
user_updateduuid | nullserverThe last writer. Set on create (= user_created) and on every update.
date_createdISO-8601 timestampserver
date_updatedISO-8601 timestampserverSet on create and on every update.
author{ id, name } | nullserverRead only, from user_created. null = the user is deleted.
editor{ id, name } | nullserverRead 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, content and slot are required, non-empty strings.
  • Update: a field that is present must be valid; title, content and slot must stay non-empty.
  • share_roles: a list of existing role ids, or null (same as []). A non-empty list needs scope: 'role'. Each write sends the full list: it replaces the stored set. When the scope changes away from role, the server removes every role link.

Slot and context_key ​

  • slot names where the template opens: namespace:name, or namespace:page:slot for 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 is core:home; the workflow inbox area is workflow:inbox:top. A module uses its own namespace. Slots are compared as whole strings.
  • context_key narrows 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 the articles list). Any other value is 400.

Defaults ​

is_default marks the template that opens by itself:

  • on a personal row: "my template" for that slot and context;
  • on a role or global row: 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 ''.

  1. The caller's own personal default.
  2. The default of a role template shared with the caller's primary role.
  3. The global default.
  4. 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 . + -, or null. Anything else is 400.
  • 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 as core:home) sends null.

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 scope other than personal;
  • sends share_roles;
  • sets is_default on a role or global row.

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:

ActionRowsFields
readown rows; role rows shared with the caller's primary role; global rowsevery field except share_roles
createscope: 'personal', user_created = the callerevery input field
updateown personal rowsevery input field; scope must stay personal
deleteown 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": "..." } }] }.

StatusCodeWhen
400INVALID_PAYLOADthe 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
403FORBIDDENno 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_count
json
{
  "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:home
json
{ "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,author
json
{ "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:x counts, Note: x is prose), no embedded x://, 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; an id must be a plain id. An image source passes isSafeImageSource when it is an inline data: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, dashboard surface) runs runtime.validate first. When it fails (a component that no longer exists, no root, 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 chat ui.present is 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 in GenUiView before the renderer, on every surface, to calls named exactly Query. 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.

ODP Internal API Documentation