> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insight.nobly.dk/llms.txt
> Use this file to discover all available pages before exploring further.

# Administration and best practices

> Manage Caseflow templates, permissions, and access control — plus implementation patterns, troubleshooting, and delivery checklists.

## Permissions and access control

The implementation enforces permission checks in multiple places:

* **Class-level create rights** for create buttons and pickers
* **Object-level rights** for modify, delete, and history in context menus
* **Template accessibility** by group matching

If users report missing actions, validate object and class privilege APIs first. If users report missing template views, validate template group assignment and default fallback configuration.

## Template administration

Template administration supports:

* Application and class selection
* Create, edit, and delete templates
* Set or unset default template
* Assign user groups
* Assign precedence
* Define template type — `Create`, `Update`, `Preview Pane`, or `Portal`

### Governance rules

* When user groups are assigned, precedence should be defined
* Precedence conflicts are blocked and reported
* Preview Pane templates are intended for read-focused search preview behavior
* Portal templates are application-scoped, not class-scoped — see [Portal templates](/caseflow/portal-templates)
* Use group + precedence for role-specific behavior
* Keep a reliable default template as fallback

## Attribute administration

The **Attribute administration** page controls per-attribute behavior across Caseflow tables and editors. For each class, the administrator can set:

| Setting                  | Effect                                                                                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Editable in bulk**     | When on, the attribute appears in the [bulk edit](/caseflow/lists-and-search#bulk-edit) attribute picker. System attributes (object ID, created date, and so on) are always blocked from bulk edit regardless of this setting. |
| **Filterable in tables** | When on, the attribute exposes a column filter button in the result table. Off-by-default attributes are still queryable through the [Search configurator](#search-configurator) but do not appear as column filters.          |

These settings drive the column filter UI and the bulk edit picker — flipping them takes effect on the next table render.

## Search configurator

The **Search configurator** is the admin UI for building and editing saved Caseflow searches. It is opened from the search list, the command bar, or the table header.

### Sections

The configurator is a tabbed dialog (resizable, \~1300 × 700 pixels by default) with the following sections:

| Section             | What you configure                                                                                                                                                           |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Class**           | The base class of the search — drives which attributes are available downstream.                                                                                             |
| **Display columns** | Which attributes appear as columns in the result table, in what order.                                                                                                       |
| **Filters**         | The user-input filter controls shown above the table, mapped to constraints on the underlying query. Includes a **Filter input mapping** dialog for searches with variables. |
| **Sorting**         | Default ordering for the result set.                                                                                                                                         |
| **Max results**     | Cap on the number of returned rows.                                                                                                                                          |
| **Configuration**   | Cross-cutting options including the **Open related path** (see below) and other behavioral toggles.                                                                          |

### Modes

| Mode           | Behavior                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| **View mode**  | Loaded with the parameters of the last executed search. No Save button. Useful for inspecting and refining a query. |
| **Edit mode**  | Loaded from a saved search. Save button is present. Changes overwrite the saved definition.                         |
| **New search** | Resets all sections and lets you build from scratch.                                                                |

### Open related path

The **Open related path** option lets a saved search resolve a dotted attribute path (for example `Task.Owner`) on each result row to a related object ID, and open that related object instead of the search row's own object when the user double-clicks a row or the row is shown in the [search preview pane](/caseflow/introduction#user-surfaces).

This is useful when a search returns rows from one class but the user's natural target is the related object — for example, searching tasks but wanting to land on the owning case.

If any segment of the path resolves to an empty value on a given row, the row falls back to opening its own object.

### Copy link

The configurator includes a **Copy link** button that generates a shareable URL for the current search. The URL preserves filter inputs, so a recipient lands on the same configured view.

## Class and attribute sync

Caseflow class and attribute metadata is synchronised from the underlying source system. The **Class & attribute sync** page in administration triggers this sync and shows the result of the last run.

| Action           | Effect                                                                                                    |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| **Run sync now** | Pulls the current class and attribute definitions from the source system into the Caseflow configuration. |
| **Review log**   | Shows what was added, changed, or removed in the most recent sync.                                        |

Run a sync after structural changes upstream — new classes, renamed attributes, or relation changes — so that templates, filters, and the [Search configurator](#search-configurator) reflect the live schema.

## Recommended implementation patterns

### Pattern A: Child records bound to current object

Use `ObjectSearch` with a relation constraint and create defaults:

```html theme={null}
<ObjectSearch
  queryKey="child-items"
  config='{
    "className":"ChildClass",
    "displayColumns":[{"dottedName":"Name"}],
    "constraints":[{"dottedName":"ParentRelation","operator":"=","value":"{{stock.objectid}}"}]
  }'
  allowCreate="true"
  createDefaults='{"ParentRelation":"{{stock.objectid}}"}'
/>
```

### Pattern B: Relation selection with attribute copy

Use `RelationPicker` with `onChanged` and `${selectedObject}` values to auto-populate fields when a relation is selected.

### Pattern C: Save-time validation rules

Use `SaveButton` with `onBeforeSave` and `throwError` to enforce business rules before persistence.

### Pattern D: Script-orchestrated post-processing

Use `ScriptButton` or `callScript` inside action chains, then refresh affected queries with `refresh:<queryKey>`.

### Pattern E: UI-only computations

Use [transient fields](/caseflow/state-and-persistence#transient-fields) (underscore-prefixed `_` fields) for temporary values and action-only orchestration.

## Common pitfalls and troubleshooting

<AccordionGroup>
  <Accordion title="No template rendered">
    Check:

    * The class has a template of the requested type
    * The user belongs to a group that can access the template, or a default fallback exists
  </Accordion>

  <Accordion title="Field does not persist">
    Likely causes:

    * Attribute name mismatch
    * Transient field (`_...`) used unintentionally
    * Relation or nested path used where only a single-level attribute is supported
  </Accordion>

  <Accordion title="Save button disabled">
    Check:

    * Validation errors exist
    * No dirty state and `requireDirty` is `true`
    * Object-level permissions are insufficient
  </Accordion>

  <Accordion title="Action not executing">
    Check:

    * Malformed JSON in action params
    * Condition in `when` resolves to false
    * Runtime variable name mismatch
    * Missing query key referenced by refresh action
  </Accordion>

  <Accordion title="Dynamic dataset not refreshing">
    Check:

    * `datasetQueryKey` is configured on the `EditableField`
    * `refreshDataset:<datasetQueryKey>` action is used
  </Accordion>

  <Accordion title="Relation auto-populate fails">
    Check:

    * The selected relation object actually contains the referenced attribute
    * Nested relation path correctness
    * Use `??` fallback for optional values
  </Accordion>

  <Accordion title="Script works in test but not in UI">
    Check:

    * Script type (`workview_autofill` vs `workview_action`)
    * Expected input payload keys
    * Execution rights and configured script engine endpoint
  </Accordion>
</AccordionGroup>

## Delivery checklist

Before go-live, confirm:

1. All business-critical classes have Create and Update templates
2. Group-based template precedence and defaults are configured intentionally
3. All search components have stable `queryKey` values where refresh chaining is needed
4. Save validation rules are implemented with clear user-facing error messages
5. Script dependencies (slugs, secrets, bindings) are deployed and tested in target environment
6. Permission-sensitive actions (edit, delete, history, create) are tested with representative user roles
7. Preview Pane templates are configured for search-heavy roles where relevant
8. Transient fields are used only for UI/runtime logic and not for required persisted data

## Implementation sequence

For new Caseflow classes, follow this sequence:

1. Confirm class/attribute model and relation paths with business owners
2. Define Create and Update templates, plus Preview Pane where search workflows demand it
3. Implement base form fields with `EditableField`, including required and regex/validator rules
4. Add relation handling using `RelationPicker` and/or `RelatedObject` aliases
5. Add object and document lists with explicit `queryKey` values
6. Attach save hooks and script actions for business automation
7. Validate role-based template access and precedence
8. Run UAT with scenario data and production-like permissions

## UAT scenario matrix

| Scenario              | What to verify                                                                |
| --------------------- | ----------------------------------------------------------------------------- |
| Create object         | Defaults applied, required fields enforced, save succeeds                     |
| Update object         | Dirty tracking works, save hooks execute in order                             |
| Relation change       | `selectedObject`-based mapping works, no stale values remain                  |
| Search refresh        | `refresh`/`refreshDocuments`/`refreshDataset` target intended components only |
| Script execution      | Success and failure branches behave predictably with user feedback            |
| Permission boundaries | Restricted users cannot create/edit/delete outside assigned rights            |
| Template fallback     | Group-specific template selected correctly; default fallback still available  |

## Production hardening checklist

1. Confirm all critical template actions reference valid query keys
2. Confirm all script slugs and required credentials/config are deployed
3. Confirm no transient fields (`_...`) are used where persistence is required
4. Confirm document upload defaults map to valid document type and keyword IDs
5. Confirm all validation error messages are business-readable
6. Confirm delete permissions and destructive actions are tested with least-privileged roles
7. Confirm object history visibility requirements with support/audit teams

## Handover package

Provide the following to operations teams:

* Template catalog by class/type with owners and change authority
* Component usage map — which templates depend on which scripts, actions, and query keys
* Script dependency register — slug, purpose, expected input/output, failure behavior
* Permission model summary — class-level and object-level assumptions
* Troubleshooting runbook aligned to the symptoms above

## Change management

For safe iterative changes:

* Promote template changes through lower environments with representative data
* Include rollback-ready version snapshots of templates and scripts
* Validate query-key refresh paths after each significant UI/action change
* Run focused regression on create, save, relation picker, and search modules