---
title: "Apps"
slug: "product-manual-compass-apps"
updated: 2026-10-29T17:36:28Z
published: 2026-10-29T17:36:28Z
canonical: "docs.ursahealth.com/product-manual-compass-apps"
---

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

# Apps

An app is a small interactive application that the AI writes for you. Where a [presentation](/v1/docs/product-manual-compass-presentations) assembles findings that were captured at a moment in time, an app queries the database every time someone opens it — so it shows current data rather than a snapshot, and it can offer controls that let the reader filter, sort, or drill into what they are looking at.

You describe what you want in a conversation; the AI writes the app and you watch it appear beside the chat. When it is right, you **publish** it, and everyone you have shared it with sees that version.

## Creating an App

The Apps list (accessible via the sidebar) shows all apps you own, can edit, or can view, sorted by last updated. It is sortable by any column and filterable by name, description, and owner. A **Status** column shows where each app stands: not started, a draft, published, or published with a newer draft in progress.

To create an app, click **New App**. Provide:

- **Name** — A descriptive title for the app.
- **Description** — Optional context about what the app is for. The AI reads this, so it is worth writing.
- **Tags** — Optional tags for categorization. Users can select from existing tags or create new ones.
- **Editors** — Compass Author-level (or higher) users or user groups granted full edit access to the app, with the same rights as the owner.
- **Viewers** — Users or user groups granted read-only access to the app.

Creating an app takes you straight to the build workspace, since a new app has nothing to show yet.

An app can also arrive ready-built, imported from the Ursa Health library rather than written in a conversation. See the [Library](/v1/docs/product-manual-compass-configuration) section of Configuration; an imported app lands as an unpublished draft that you review and publish like any other.

## The Foundation

Before the AI can write anything, it has to declare what the app reads. It does this with the SET_FOUNDATION tool, naming [data model objects](/v1/docs/product-manual-compass-data-model), [Compass objects](/v1/docs/product-manual-compass-objects), [measures](/v1/docs/product-manual-compass-data-model), or any mix of them. You will see this as one of the first steps in the conversation.

Declaring a source hands the AI the exact names of the functions it can call, the columns it may group by, the columns it may aggregate, and the type of every column. It is also the app's data grant. A viewer of a published app can read only what that revision declared. Sharing an app with someone is therefore also granting them read access to those sources, through this app.

A Compass object can be declared as its draft, `compass.<table name>`, or its published version, `ursa.<table name>`. Either works while the app is being built, but an app cannot be published while it reads a draft, so its Compass objects need to be published and declared by their `ursa.` names first.

### Building on a Measure

A measure is not queryable on its own — it only has data where a report has instantiated it. So a measure is declared along with the report it is read through, which decides the reporting period and other report-specific metadata.

An app reading a measure follows the measure's own arithmetic rather than treating it as a table of numbers. A measure's rows carry a numerator and a denominator, and the figure the measure reports is the one over the other, summed across whatever the app has grouped by.

A [Compass object](/v1/docs/product-manual-compass-objects) that declares itself measure-like is read with the same arithmetic, and needs no report.

### Capturing Feedback

An app can record what its users say about individual rows, such as whether an encounter has been validated, what review status a case is in, or a free-text note.

The feedback belongs to that app, not to the object. That is to say, two apps built over the same object each keep their own, and neither can see the other's. Anyone who can see the app can add feedback, and each row of feedback records who gave it and when.

Feedback can only be recorded at the level of a case field, so it is not available for long-form measures, interval measures, or other structures in which the case-grain is not the row-grain.

Removing a field later stops it appearing in the app, but does not delete what people already entered — so a field cannot be renamed by dropping it and adding it back under a new name.

## Building an App

Owners and editors open the build workspace with the **Build** button on the app's page. The workspace has two parts:

- **The conversation**, where you describe what you want and the AI reports what it did.
- **The app itself**, in the upper right, rendered at a realistic width and scaled down to fit. It reloads on its own each time the AI saves a new version, so you watch the app change as you talk about it.

Everything in the app is live: the figures in the corner are real query results against the client database.

### Working on a Second Screen

The corner preview is small. The icon in its header opens the app in a new browser tab, which you can move to a second monitor and leave open while you work. That tab is not a static copy — it updates the moment the AI saves a change, exactly as the corner preview does, without being touched or reloaded.

The tab shows your draft, and a draft is visible only to owners and editors. If anyone else opens that address, they get the published version instead — or the note that the app has not been published yet.

### Interrupting the Builder

While the AI is working, the owner or an editor can click the **Interrupt** button to stop it mid-build. The AI stops at its next tool call boundary, acknowledges the interruption, and asks how you would like to proceed. The last version it saved before the interruption is preserved and still shows in the preview.

### What an App Can and Cannot Do

An app can read what it declared, hold state, respond to controls you interact with, lay out tables, metrics, and cards, and render charts. It is styled to match Compass automatically, including Light and Dark Mode — charts included, so there is no need to ask for a particular color scheme.

An app is also written under a deliberately narrow set of capabilities. It has no imports, cannot fetch from an address of its own choosing, cannot reach the page around it, and cannot navigate, apart from handing a question off to Explorer, described below. The two things it can write are the feedback it declared, described above, and a file it downloads to a reader's own machine, described below; beyond those it stores nothing outside its own state.

### Downloading

An app can offer to download what it is showing — the rows behind a table, as a CSV assembled by the server; a file the app composed itself, such as a summary it built from several queries; or a chart, saved as a PNG image from a menu on the chart. Ask for it in the conversation and the AI will add the control.

Downloading is a privilege, not a feature of the app. It is available only where the installation permits downloading to a local machine at all, and then only to readers who have been granted permission to download protected health information — the same permission that governs downloads elsewhere in Ursa Studio.

The app knows whether the person reading it holds that permission, so two people can open the same app and see different things. What a reader without it sees — nothing at all, a disabled control, or a note explaining why — is up to how the app was built, so say what you would prefer when you ask for the feature.

Each reader's permission is checked again on the server every time a download is attempted, so what an app offers is never what decides whether a download happens. Every download is written to the audit log, recording who downloaded what.

Downloads are capped at a large but finite number of rows. A download that would exceed the cap is refused, with a message asking you to narrow the filters, rather than quietly handing you a file that stops partway through.

### Handing Off to Explorer

An app can offer a control that opens an [Explorer](/v1/docs/product-manual-compass-explorer) session in a new tab, with a starting request already written — for example, a question about the row or chart the reader clicked. The reader sees Explorer's new session page with the request filled in, and can edit it before starting the session.

The app can also name the persona the session should default to. If a persona by that name exists, it appears in the dropdown and is selected, even when the reader has not added it to their explorer personas; if it does not exist, Explorer falls back to the reader's usual default.

Only readers who can use Explorer are offered the control. Ask for it in the conversation, and say which persona you would prefer.

### Persistence

Each app has one conversation, which lasts for the life of the app. It is saved automatically, so leaving the workspace and returning later resumes where you left off, with everything the AI has already learned about your app still in context.

### Compacting the Conversation

A long conversation slows the AI down and makes it costlier, and early details can get lost in it. The **Compact Conversation** button on the app's page replaces most of the conversation with a summary. The AI keeps:

- its setup instructions, rebuilt to reflect the current installation,
- your starting request, word for word,
- a summary of the rest of the conversation: your lasting preferences, what has been done, and what is still open,
- the app's current data declarations and component, exactly as saved,
- its last question to you, if you have not answered it yet.

The summary appears in the build workspace's conversation as a **Conversation compacted** entry, which you can expand to read what the AI was told. The messages it replaced are no longer sent to the AI, but they are kept: **Show earlier messages** above that entry brings them back into view, dimmed. Compacting cannot be undone, and you can compact again later as the conversation grows.

Feedback is stored apart from all of this, and outlives any one revision of the app. Publishing a new revision, or rewriting the app entirely, leaves what people have entered untouched — as does the nightly rebuild of the objects and reports the app reads. Deleting an app deletes the feedback collected in it.

## Publishing

An app has at most two versions at any moment:

- A **draft**, which only owners and editors can see. This is what the AI edits and what the build workspace shows.
- The **published** version, which is what everyone you shared the app with sees.

Iterating on an app changes nothing for anyone else. Nothing you do in the workspace becomes visible to anyone until you publish it.

Published versions are kept permanently. Publishing does not overwrite the previous published version; it adds a new one. Editing after publishing starts a new draft.

If you have a draft that is newer than what is published, the app's page says so in a banner, with the version numbers of both, and offers **Preview Draft** to see what you have been working on and **Show Published** to switch back to what everyone else sees.

## Sharing

Apps are private by default — only the owner can see them. To share an app, add individual users or user groups as editors or viewers on the app form.

- **Editors** have the same rights as the owner: they can build the app, publish it, edit its metadata, and manage who else has access. Only Compass Author-level users (or higher) can be added as individual editors; any user group can be added as an editor group. When a user group is added as an editor, all members of that group receive editor-level access.
- **Viewers** have read-only access to the published version of the app. Any authenticated user or user group can be added as a viewer. When a user group is added as a viewer, all members of that group receive read-only access.

Removing all editors and viewers (both individual and group) makes the app private again.

## Row-Level Security

Sharing an app grants read access to whole objects and measures. Row-level security narrows that to the rows a particular reader is entitled to, using the [entities](/v1/docs/product-manual-compass-entities) each user is associated with.

The **Row-Level Security** dropdown on the app form offers:

- **No row-level security** — every reader of the app sees every row of what it declared. This is the default, and how apps behaved before this setting existed.
- **Row-level security via direct filter** — every read is filtered to the field values of the entities the reader is associated with.

An entity records the column that identifies it and the value in that column — say `payer_name` and `Aetna`. Turning row-level security on asks you to say which column carries each field name on each source the app declared. That grid appears under the dropdown, alongside a table of everyone who can read the app and the entities each of them is associated with.

A reader with no entity association is not restricted at all; they see every row, exactly as if the setting were off. The readers table highlights these people for that reason. Restricting someone requires associating them with an entity. Someone associated with both a payer entity and a region entity sees the payer's rows *and* the region's rows, not only the rows that are both. If a reader carries a field name this app has not mapped for the object being asked for, the read fails rather than returning unfiltered rows. The grid says so next to any mapping you have left blank.

The filtering applies to everyone reading through the app on the same terms, the owner and editors included — their own entity associations decide what they see, and an author with no entity association sees everything. It applies to recording feedback as well as reading: a row you cannot see is a row you cannot annotate.

## Editing and Deleting

Owners and editors can edit the name, description, tags, editors, and viewers from the app's page via **Edit Metadata**. The edit form also provides a **Delete App** option, which soft-deletes the app — it is hidden, but the underlying data, including every published version, is retained.

Editing metadata does not affect the app itself or its conversation. Renaming an app does not require republishing it.

## Access Control

- **Compass Authors** (and above) can create apps, build them, and publish them.
- **Viewers** can open apps shared with them and read the published version. Any authenticated user can be a viewer.
- **Reviewers** can open apps shared with them as viewers but cannot create apps or be added as editors.
- **Editors** and **owners** can build, interrupt a build in progress, compact the build conversation and view what it replaced, publish, edit metadata, delete, and manage sharing. Only Compass Author-level users (or higher) can be editors.
- **Handing off to Explorer** is available only to readers who can use Explorer (Reviewers and above).
- **Downloading** data out of an app requires permission to download protected health information, and requires that the installation permit local downloads at all. It is a separate privilege from reading the app: being an owner or an editor does not confer it.

Every read an app performs, for every viewer, writes an entry to the audit log recording who read which object, how it was filtered, grouped and sorted, and which page of rows it asked for. Every download writes its own entry alongside them.