ObjectSearch
Query and render objects in table, cards, or list format with row actions, editing, and create support.Key capabilities
- Declarative query config with class, display columns, constraints, and sorting
- Row context menu — edit, delete, documents, history
- Editable mode with modal editing
- Inline cell editing on the result table — see Inline cell editing
- Create mode with defaults
- Optional per-row document lookup via
documentSearchConfig - “Open related” navigation that resolves a dotted attribute path to a related object — configured per saved search in the Search configurator
queryKeyfor targeted refreshitemTemplateNamefor card/list rendering
Props
ObjectSearchConfig shape
Examples
Editable list with create and targeted refresh:${row.*} variables:
Item templates
An item template renders one search row. Its scope is the row’s own object, so{{Name}} is that object’s own
Name attribute. The configured display column values are available under columns, keyed by the column’s label,
or by its dottedName when it has no label. That is how a card shows values from a related object:
OfferCard template:
- Keys are used exactly as written.
{{columns.Offer ID}}and, for an unlabelled column,{{columns.VehicleRelation.Model}}both work in text and in props. - In a condition (
{{#if …}}), give the column a label made of letters, digits and dots only: no spaces, parentheses, quotes or operator characters such as!,=,<,>,&or|. For example{{#if columns.Make}}works, but a column labelledOffer IDorAmount (DKK)can’t be tested in a condition. - Values are the search result as text: dates arrive as ISO text (for example
2026-10-01T00:00:00) and numbers are not localized, so wrap a date in<DateDisplay value="{{columns.Presented}}" />as above. - Values are those from when the search ran. After an edit inside the card,
{{columns.X}}keeps the old value until the search refreshes, so use{{AttributeName}}for the row’s own attributes that the card edits. - A null value is empty in
columns. The table, cards and list displays show it as—. - Templates that don’t use
columnsrender exactly as before. - If the search doesn’t return a configured column, ObjectSearch shows a warning naming it (for example “Column ‘Make’ (VehicleRelation.Make) was not returned by the search”) instead of leaving it silently empty.
Click to select
UseselectInto for master/detail views: one click selects a row or card, a double click opens it. Without selectInto, the existing click behavior is unchanged.
An
ObjectSearch inside an item template with the same selectInto hands its selection to the outermost ObjectSearch that declares the field, so a click on a card at any depth of a recursive tree selects into the view. The item template can read {{selection.isSelected}} ("true" or empty) to style the selected card. Fields that start with _ are transient: selecting never marks the object as changed and never touches unsaved edits.
onSelect runs after a selection in the view’s context, so setValue writes to the view. A newer selection cancels the actions of an older one that has not run yet.
Pair it with a reactive DocumentSearch to show the selected object’s documents:
DocumentSearch
Query and render documents from a document search configuration with optional upload support.Props
Filter values can read the object store with
${...}; the search does not run while a referenced value is empty. Without reactive, such a search runs again only on refreshDocuments:<queryKey> and keeps showing its previous results while it reloads.
Preview a document without leaving the view
Withpreview="modal", every result gets an eye button. It opens the document in a pop-up over the view, where you can page through it. The pop-up closes with its close button, Escape, or a click outside it, and leaves the view as it was: the same scroll position and selection, and any unsaved edits untouched. Previewing never changes the record. The eye button is its own click target: it does not open the document in a new tab or select the row.
Add previewWithKeywords="true" to show the document’s keyword panel beside it, in a split you can resize and collapse. Keyword edits there are saved to the document with the user’s own rights; they never change the Caseflow record. On screens narrower than 1024 px the pop-up fills the screen.
preview takes only none and modal here. An inline preview exists only on RelatedDocument. The template editor warns about preview="inline", about preview="true", and about previewWithKeywords without preview="modal"; those settings have no effect.
Common enum values for configs
Examples
Baseline document search:DocumentChat
An AI question-and-answer chat over the documents aDocumentSearch config matches, inside the object’s view. Answers carry document and page references; a click opens the cited page in Caseflow’s preview pop-up (the same as preview="modal") without leaving the view. Where an answer refers to a Caseflow object, a click opens the object in a new tab. The user can ask follow-up questions in the same conversation, end an answer while it is being written with Stop, and start over with New conversation.
Prerequisites
- AI chat is available to the user. It is off unless it is switched on for your environment, and where features are controlled per user group, one of the user’s groups needs AI document search chat under Admin settings → Access → User Group Access. The panel checks this first and otherwise shows AI chat is not available to you here.
- An AI search agent under Admin settings → AI Assistant → Agents with keyword types (its keyword boundary), offered to the user groups that use the view, and with Caseflow templates ticked under Offered in. Untick AI chat there if the agent should only be used from templates. See AI agents and shared settings.
- The documents are indexed for AI search.
Props
Agent by name
Like classes and attributes in a template, the agent is referred to by its name, never by its id. Ids differ between environments; the name is what the template keeps when it is promoted.- The name is matched against the search agents the user may use that are offered in Caseflow templates. Matching is exact, ignores case, and ignores leading and trailing spaces.
- The chat never falls back to another agent.
States
Instead of the question field, the panel shows a state when the chat cannot start:
When some, but not all, documents are indexed, the scope line says how many the AI cannot read.
What the server enforces
- The conversation uses exactly the agent the template names. The server checks the config against that agent alone and refuses it when the config does not satisfy the agent’s boundary.
- The agent must be offered to one of the user’s groups.
- When the conversation is created, the server fixes its scope to the documents the config matches. Every answer, including follow-ups, is retrieved from that set only; a question cannot widen it. To ask about another object, the panel starts a new conversation.
- The user’s own document rights still apply.
- An agent offered in Caseflow templates cannot be saved without keyword types.
previewWithKeywords) saves keyword edits with the user’s own rights, as on DocumentSearch. Conversations appear in the user’s AI chat history.
The panel shows no approval cards for keyword changes the agent proposes. For an agent offered in Caseflow templates, set propose_keyword_updates to Off under the agent’s Tool overrides.
In the template editor’s preview nothing is saved: asking a question starts no conversation and shows Not available in preview, the question stays in the field, and the citation pop-up’s keyword panel is read-only.
Example
The documents of the object selected in anObjectSearch with selectInto="_SelectedObjectId":
CreateObjectButton
Open a create modal for a class and optionally run post-create actions.Props
Example
Create with refresh and local update:SaveButton
Save dirty objects within a controlled scope with before/after hooks for validation and automation.Props
Save hook runtime variables
${changedFields}— array with utilities like.includes("Field"),.length,.join(", ")${oldValues.AttributeName}${newValues.AttributeName}
Examples
Save-time validation gate:ScriptButton
Run a script directly from the UI with input mapping and result-driven follow-up actions.Props
Example
Script output projected to field:WorkflowTasks
List the workflow tasks offered on the current object, so people can complete them without leaving the case. Inside aRelatedObject, it lists the related object’s tasks.
A task is listed only when the workflow author switched on Also show on the document or object for it; every other task stays on the Tasks page only. Tasks are grouped by workflow, with the step each one is on. Who sees a task, and the inputs it asks for, are the same as on the Tasks page; see tasks on the document or Caseflow object. After a task completes, the object’s values are reloaded. Unsaved changes are kept, and the person is asked to save and reload.
The element shows nothing while the object is being created, while its tasks load, or when they cannot be loaded. With no tasks, the button is hidden, while the inline list says No tasks right now., so a tab that holds only the list is never blank.
Props
Examples
In a header:Internal support components
These components are used internally by the Caseflow runtime. They are not available as template tags but are important for understanding the system.ObjectModal
ObjectModal
Modal shell for template-driven create/edit operations. Used by
ObjectSearch and CreateObjectButton.- Create mode initializes a new in-memory object state and can apply defaults
- Edit mode binds to an existing object key
- Resolves and renders the chosen template (Create or Update)
- Handles save mutation and callback orchestration (
onCreated,onSaved) - Can open created object in a new tab
- Invalidates related query keys after save so dependent UI refreshes
- If closed before first save, unsaved temporary state is cleaned up
- If no template exists, a clear fallback message is shown
DocumentsModal
DocumentsModal
Modal wrapper around
DocumentSearch with resolved config. Used by ObjectSearch row actions for “view related documents”.- Receives already-resolved configuration from parent (including row-variable substitutions)
- Shows loading state while configuration is being prepared
- Renders
DocumentSearchin table mode with header enabled
DocumentPreview
DocumentPreview
File preview renderer with revision/rendition selection and live refresh. Used by
RelatedDocument preview modes.- Fetches revisions and renditions for a document
- Picks latest revision and default rendition for preview
- Subscribes to document revision events and refreshes automatically
- Returns structured loading, empty, and error states
ItemTemplateRenderer
ItemTemplateRenderer
Renders one search result item using a named Caseflow template for cards/list displays. Used by
ObjectSearch when display="cards" or display="list".- Creates an isolated object provider per item (no row-to-row state bleed)
- Fetches the named template for the row’s class in update context
- Builds item scope with regular attributes, stock attributes, user context, and alias scopes
- Adds the row’s display column values as
columns.*— see Item templates
ObjectHistoryDialog
ObjectHistoryDialog
Shows object audit details in a dialog with two data views. Used by
ObjectSearch row action “View history”.- Attribute Changes tab — flattened transaction/attribute change rows
- Event Log tab — event timeline with translated event types
- Loads history only when dialog is open
- Formats UTC timestamps for readable presentation
Complete component inventory
Where to read next
Lists, saved searches, and search operators
Configure Caseflow saved searches and folders, result tables, typed column filters, bulk actions, inline editing, and search operators.
