Entities

An entity represents an organization, partner, or other grouping that can be associated with diagnostics and presentations. When a diagnostic is linked to an entity, the AI is automatically instructed to filter its queries to that entity's data.

Creating an Entity

From the Entities list (accessible via the sidebar), click New Entity. Provide:

• Name (required) — The name of the entity (e.g., "Acme Insurance").
• Dimension — Optional grouping category (e.g., "Payer", "Provider Network"). You can select an existing dimension or type a new one. The entity list groups by dimension.
• Notes — Optional free-form notes about the entity.
• Field Name (required) — The database column name used to identify this entity's data (e.g., payer_name).
• Field Value (required) — The value in that column that corresponds to this entity (e.g., Acme Insurance).

How Entity Filtering Works

When a diagnostic is associated with an entity that has a field name and field value, every session in that diagnostic automatically receives an entity filter instruction in its prompt. This instruction tells the AI:

• The analysis is restricted to the named entity.
• All queries at the entity scope must filter on the specified field name and value.
• It is acceptable to bring in data from other entities at the aggregate level for baselines or comparisons, but entity-level data should always be filtered.

The entity filter appears in the Prompt Preview on the diagnostic form, so you can see exactly what the AI will receive. It is injected after the tool prompts and before the starting request.

Importing Entities from the Data Model

If the Business Entity Reference table (mi_ursa_core_150) exists in the client database, entities can be bulk-imported by clicking Import Entities from Data Model in the upper-right of the entity list. A confirmation dialog appears before the import runs.

The import maps the following columns from mi_ursa_core_150 to entity fields:

• business_entity_id → used as the import key to identify previously imported entities
• business_entity_desc → Name
• business_entity_dimension_desc → Dimension
• business_entity_compass_usage_comments → Notes
• standard_business_entity_code_field_name → Field Name
• business_entity_code → Field Value

The import uses upsert logic: new rows are inserted, and previously imported rows (matched by import key) are updated. If an entity was deleted and still exists in the reference table, it is restored. Notes that have been added manually in Compass are preserved if the reference table has no notes for that entity.

After the import completes, a summary message shows how many entities were imported and how many were updated.

Entity List

The entity list shows all entities, grouped by dimension. Entities without a dimension appear under "Other" at the bottom. Each entry shows the entity name, field name/value, and notes.

Associating Entities with Diagnostics and Presentations

Both the diagnostic form and the presentation form include an Entity dropdown and a Vintage text field. Select an entity to associate it; the vintage field is free-form text for identifying data periods (e.g., "2024 Q3", "CY2025").

On the diagnostic detail page, the entity name and filter criteria are displayed below the domain.

Entities in the Opportunity Scan

The opportunity scan includes an entity filter dropdown when any opportunity scan diagnostics or presentations are associated with entities. Selecting an entity filters the opportunity scan to show only diagnostics and presentations linked to that entity. When an entity is selected, a vintage dropdown also appears, populated by the distinct vintage values from the filtered diagnostics and presentations.

Access Control

• Authenticated users can view the entity list.
• Compass Authors (and above) can create, edit, and delete entities.