Search Utilities
Search Utilities is the system-level administration page for the platform’s search infrastructure. It shows the live health of all search components, displays index statistics per entity type, and provides action buttons for maintenance operations including full index rebuilds, entity-scoped reindexing, and destructive cache clearing. Use this page when search results are stale, incomplete, or when a microservice reports missing indexed data.
Accessing the Page
Section titled “Accessing the Page”- Route:
/search-utilities - Menu Path: Settings → System → Search Utilities
- Primary audience: System administrators only. Accessed via the system admin login at
system.portal.net— not the tenant portal.
What you can do here
Section titled “What you can do here”- View the overall health of the search service and the status of each internal component (Index Rebuild, Schema Cache, Data Cache, PostgreSQL Fallback, RabbitMQ).
- Review statistics: total registered schemas, total indexed entities, and per-entity-type counts with their micro-service association and search score weight.
- Rebuild the entire search index from scratch (destructive — use only when other actions are insufficient).
- Reindex all registered entity types across all connected services in a single operation.
- Reindex a specific entity type without affecting others.
- Clear the term index (destructive — removes all indexed terms; search will be unavailable until reindexing completes).
- Clear the index for a single entity record by type and ID (targeted cleanup for a corrupted or orphaned entry).
Common tasks
Section titled “Common tasks”- Open Settings → System → Search Utilities at
system.portal.net. - Check the Health card — all components should show a healthy status. If a component is unhealthy, investigate the root cause before running maintenance actions.
- Check the Statistics card for entity counts per type. If a count is lower than expected, run a targeted reindex for that entity type.
- For widespread stale results across multiple entity types, use Reindex All Services.
- For a single entity type that is missing or out of date, use Reindex Entity Type and select the type from the dropdown.
- Verify the entity count in the Statistics card has returned to the expected value after the operation completes.
- Actions that trigger async processing (Reindex All, Reindex Entity Type) send a command and return immediately. The Statistics card may not reflect the updated count until the background job finishes.
- The Rebuild Index action rebuilds the entire index from scratch and shows a live progress bar. It runs synchronously and may take several minutes on large datasets. Only trigger it if a full rebuild is necessary.
- Clear Term Index is irreversible and makes search unavailable until indexing is complete. A confirmation dialog is required. Use only as a last resort for catastrophic index corruption.
- Clear Entity targets a single record by type and ID. It removes that record from the search index without affecting others. Use it to resolve duplicate or orphaned search results for a specific item.
- The RabbitMQ status in the Statistics card shows whether the search service can receive async indexing messages. If disconnected, real-time index updates will not be processed — only manual reindexing will update the index.
- The tenant context selector (if shown) lets you scope statistics and actions to a specific tenant. Leave it empty to operate at the platform level.
Available Utilities
Section titled “Available Utilities”Health Check
Section titled “Health Check”Displays the live status of all search service components. Refresh the card at any time using the refresh button.
| Component | What it reports |
|---|---|
| Index Rebuild | Date and time of the last full rebuild, or a warning if no rebuild has ever run |
| Schema Cache | Number of entity schemas registered in the cache |
| Data Cache | Number of entities currently cached in memory |
| PostgreSQL Fallback | Whether the PostgreSQL persistence layer is available and the count of persisted entities |
| RabbitMQ | Whether the message broker connection is active (Connected / Disconnected) |
Index Statistics
Section titled “Index Statistics”Shows a table of all registered entity types sorted alphabetically. For each type, it shows:
- Display name — localized label (falls back to the internal entity type key if no translation is registered)
- Micro-service — the service that owns the entity type
- Score weight — the relative search relevance weight for this type
- Count — total indexed records of this type
Rebuild Index
Section titled “Rebuild Index”Drops and rebuilds the entire search index. A progress bar tracks processed vs. total entities and the estimated completion percentage. The last rebuild status (Completed, Failed, or Running) and duration in seconds are shown after completion.
When to use: the search service reports structural schema errors, or a previous rebuild failed midway and left the index in an inconsistent state.
Reindex All Services
Section titled “Reindex All Services”Sends a reindex command to all registered microservices simultaneously. Both local in-process indexing and remote async reindexing via RabbitMQ are triggered. A success toast shows the total operation count, split by local and remote.
When to use: search results are stale across multiple entity types after a data migration, import, or deployment.
Reindex Entity Type
Section titled “Reindex Entity Type”Select a specific entity type from the dropdown and click the action button. If the operation is handled asynchronously, a “command sent” confirmation is shown. If handled synchronously, the updated entity count is displayed immediately.
When to use: one particular entity type (e.g., Business Partners or Items) shows missing or outdated results while other types are healthy.
Clear Term Index
Section titled “Clear Term Index”Permanently removes all indexed terms from the search index. A confirmation dialog warns that search will be unavailable until reindexing is complete. The dialog requires an explicit confirmation click to proceed.
When to use: the term index is corrupted and preventing the search service from starting cleanly. Always follow this action with a Reindex All Services or Rebuild Index operation.
Clear Entity
Section titled “Clear Entity”Removes a single record from the search index by specifying its entity type and record ID. No confirmation dialog is shown — the action executes immediately on button click.
When to use: a specific record appears duplicated or shows stale data in search results and a full reindex is not practical.
Related Pages
Section titled “Related Pages”- Micro Services — service registry; check that all services are active and healthy before running reindex operations
- Tenant Management — when scoping search actions to a specific tenant