Skip to main content
Version: 3.3

Database Inspector & Diagnostics

Cortex includes diagnostic tools accessible from the Database Inspector for troubleshooting archive data sources. These are available by navigating to Admin → Database Inspector and selecting the relevant data source.

About This Database​

The Inspector's first tab, About This Database, summarises the archive itself rather than diagnosing a specific problem:

  • Database - the data source name, the database name, and the engine Cortex is reading through.
  • Globalization - the primary culture (the culture the system was installed or upgraded in; it is the source culture and cannot be deleted), the preferred culture (the first fall-back used when a translation is missing), the multi-byte and right-to-left flags, and every enabled culture with its code and native name.
  • System default culture - the culture Cortex reads from the BusObInitLocalization setting on startup. If Cortex cannot determine it - the setting is missing, or the stored value does not match a known culture - the tab warns, names the fall-back Cortex is using instead, and offers a Show SQL to set BusObInitLocalization button that opens a culture picker and generates the SQL to set the setting.
  • Content version - the archive's content version, which loads after the rest of the tab so the page appears immediately.

Globalization details are available for Cherwell archives that carry a globalization settings definition; a database without one says so instead.

Available Diagnostics​

Table Sizes​

Displays per-table on-disk size and estimated row count for the selected archive, sorted from largest to smallest. This is useful for identifying which tables consume the most storage and understanding the scale of data in your archive.

The tool is engine-aware and uses the cheapest available catalog views for each database type.

Orphaned Assignments​

(Cherwell archives) Finds teams and users that are still assigned to records but no longer exist in the archive's TeamInfo / UserInfo tables. These orphaned assignments can cause data validation issues during data migrations to another platform, where the assignment cannot be resolved.

Cortex works out per table whether the assignments use the AssignedTo / AssignedTeam pair or the older OwnedBy / OwnedByTeam pair, so tables with either convention are covered.

Two scopes are available:

  • All Major Business Objects - scans the major business objects and shows only the tables that have findings.
  • A single table - always reports the result for the table you pick, including when there are no orphaned assignments.

Results are listed per table as the orphaned users and the orphaned teams found there, so you can hand the list to whoever owns the data before a migration.

Search for a specific value across all tables and columns in the archive database. This is useful for locating records when you know a value (e.g., an email address, ticket number, or asset tag) but aren't sure which table or column it's stored in.

  • Supports exact match and substring search
  • Reports which database table, Cortex table, and column contain the value
  • Live counter shows progress as tables are scanned
  • Generate Full Query button produces the actual SQL for reference
  • Configurable timeouts to prevent long-running scans

Attachment Finder​

Diagnose attachment loading issues by finding the first record that actually has a loadable attachment.

  1. Select a table from the dropdown.
  2. Cortex scans candidates rediscovering each via the real attachment path.
  3. Results show the found record's fields and attachment list.

If no loadable attachments are found, the tool reports how many candidates were inspected and why they failed.

User Mapping​

(Cherwell archives) Reproduces the login-time Cherwell user lookup for a single identifier and reports the result of every branch. Use it when a user signs in successfully - typically through SAML or Windows Authentication - but is not mapped to their Cherwell account, so they see no Cherwell data. A missed lookup is otherwise silent.

The tool is read-only. It runs the same Email, Windows and Username lookups the login path runs and never writes or changes a mapping.

  • Effective configuration - the configured authentication type, the effective and configured LookUpBy, the identifier claim, whether the data source matches Windows identities by logon name only, and the current user's resolved Cherwell RecID.
  • Identifier to test - pre-filled with the current user's identity so you can test myself first; type any login name, DOMAIN\login or email address to test another user.
  • Override lookup mode - leave it off to use the configured LookUpBy, or turn it on to see what each mode (Email, Windows, Username) would resolve on its own.

Click Test lookup. The result starts with a verdict and the matched record, then:

  • Observations - the findings that explain a miss, including the most common ones: an exact WindowsIdentifier match found nothing but logon-name-only matching would have matched (turning on Match Windows-authenticated users by logon name only for the data source fixes that user); a match exists under a different mode than the configured LookUpBy; or a UserInfo row matched by email but no TrebuchetAuth row points at it.
  • Branch probes - one row per branch (Email, Windows exact, Windows logon name only, Username) showing whether it matched and the identifiers and record it found.
  • Resolved records - the matched TrebuchetAuth row, its UserInfo row and the security group definition Cortex resolved.
  • Cortex-side rows for this identifier - the UsersToSecurityGroups and UserCherwellUserRecIdMapping rows for the identifier.

A Search Cherwell users (candidate list) box runs the same search behind the Users page's Search Cherwell user... dialog and annotates the results with near misses (differs only by case, differs only by domain prefix), which is useful when the identifier the identity provider sends is close to - but not exactly - the stored one.

(ServiceNow archives) Diagnose why related list tabs on record forms appear empty.

Pick the table you are investigating, and - when the record form you are looking at uses a specific form view - pick that view as well. The view list is built from the views that actually have related-list headers, with the Default view first, so the scan reflects the headers a record under that view would really use.

For each related list, the tool reports:

  • Ok/Tab — the related list is renderable
  • Missing table — the related list's target table does not exist (common with task-subclass TPH tables sharing the task physical table)
  • Missing reference column — the reference field is not found on the physical table
  • Missing mapping — the reference field cannot be mapped to a physical column
  • Self-reference/Duplicate — the related list references the same table or is a duplicate
  • Virtual/redirect — the related list is a virtual table or redirects to another table

A scan also reports the outcome of the resolution as a whole:

  • An outcome indicator — success, a warning when Cortex had to fall back to the Default view's headers (so the form may be showing a different set of tabs than the view you selected), or an error when related lists were expected but nothing could be rendered.
  • A plain-language verdict, which separates the three situations worth telling apart: the table has no related-list metadata at all and nothing is expected, headers exist but nothing they reference can be found on the mirror, or Cortex resolved the tabs by falling back to the Default view.
  • A Resolution trace — the view that was requested, the headers that were loaded and which views they belong to, whether a fallback happened, how many entries were examined, and how many tabs were finally rendered.
  • A View column on the per-entry reasons grid, showing which form view each entry came from.

The diagnostic uses the same real resolver path as the record form UI, so results match exactly what users see.

View Query Diagnostic​

(ServiceNow archives — admin only) On each related list tab, click to capture the exact SQL and parameters Cortex uses to load that tab. This helps diagnose why a related list returns no results or errors, by showing you the actual query sent to the database.

Reference Field Diagnostic​

(ServiceNow archives — admin only) When a reference field on a record form appears blank, click the info (i) icon next to the field to open the diagnostic dialog. It shows:

  • Dictionary metadata for the field
  • The resolved target table
  • The display column and why it was chosen
  • "Why display is NULL" — the specific reason the display value is empty
  • The exact SQL Cortex uses to populate the field

This is especially useful for vendor mirrors with unusual physical naming conventions.

Field Type Mismatch Tool​

(ServiceNow archives) Identifies columns where the sys_dictionary expected data type differs from the actual physical DATA_TYPE in the database. Type mismatches cause errors like operator does not exist: text <> numeric in PostgreSQL.

Each match shows:

  • Expected type (from sys_dictionary)
  • DB column type (actual physical type)
  • Current type (with override badge if already fixed)
  • Editable dropdown to suggest a fix, which upserts a ServiceNowFieldTypeOverride

Note: This diagnostic was absorbed into the Related List view in the Database Inspector.

Theme Definitions Browser​

(Cherwell archives) Browse and debug theme information from your Cherwell database. Supports both legacy and G2 Universal themes.

  • View all ThemeDefs with raw XML
  • Browse ThemeItemList with color preview swatches
  • View ThemeCustomColorAssociation ID-to-PaletteColor mappings
  • Browse PaletteColorList and CustomPaletteColorList

See the Cherwell Theme System page for details on theme definitions and debugging.

Style Debugger​

(Cherwell archives) Double-click any form control in the Inspector to see the resolved colors (background, foreground, border) with full resolution chain traces, including G2 palette color lookups.

Blocked Database Requests​

Monitors and reports on database queries that are blocked or taking longer than expected, helping identify performance bottlenecks across all archive data sources.