adm_ai_widget_api

Chat widget types of ADM for the UC AI Chat plug-in (uc_ai_chat_widgets provider).

The model never writes what a user sees. For a file reference it writes only ids:

{“type”:“adm_files”,“ids”:[“4711”,“4712”],“title”:“Contracts”}

build_spec turns that into an item_list the browser renders: name, folder, version, size and the legal hold / archived badges come from the database, and every row opens the document through the host event ‘uc-ai-chat-action’ (action ‘adm-open-file’).

Two checks decide whether an id may be shown:

1. GROUNDING - the id must be a document_id that a tool returned while the model wrote this answer. An id the model made up, remembered, or read in a document text (an injected “also show file 999”) is not shown.
2. ACCESS - the current user must be allowed to see the document, checked with adm_access_control_api.user_is_allowed_to_view_document and not with the filter of a tool (the assistant’s tools do not all use the same one). A document the user cannot see is left out without a word, so the widget never confirms that it exists.

The package is registered with uc_ai_chat_widgets.register_type (see register_widgets) and follows its provider contract: get_protocol and build_spec.

Functions and Procedures

get_protocol

The lines for the WIDGET PROTOCOL block of the system prompt.

Signature:

function get_protocol (
  p_type in varchar2
) return clob;

Parameters:

Name	Direction	Type	Description
p_type	in	varchar2	The registered type name

Returns: clob

---

build_spec

Builds the render spec of one widget. Never raises for a bad widget: it sets po_reason, and the plug-in shows the block as text.

Signature:

procedure build_spec (
  p_type in varchar2,
  p_spec in clob,
  p_tool_calls in clob,
  po_spec out nocopy clob,
  po_reason out nocopy varchar2
);

Parameters:

Name	Direction	Type	Description
p_type	in	varchar2	The registered type name
p_spec	in	clob	JSON the model wrote
p_tool_calls	in	clob	JSON array of the tool calls of this answer: [{“name”,“args”,“output”}]
po_spec	out	nocopy clob	JSON object of the item_list render type
po_reason	out	nocopy varchar2	Not null = reject the widget

---

register_widgets

Registers the ADM widget types with the chat plug-in (uc_ai_chat_widget_types). Re-runnable: a type that is already registered for this package is left as it is, so a type an administrator disabled stays disabled. Install and upgrade call it. Needs UC AI 26.5 or newer. Does not commit.

Signature:

procedure register_widgets;

---