Blueprints

The Blueprints section of the Refinery Studio lets you browse the blueprint catalog of your environment, install or re-apply blueprints on the current tenant, and inspect what is already installed.

A blueprint is a versioned bundle of Construction Kit models plus seed data that puts a tenant into a working state. For the underlying mechanics see the tech guide: Blueprints.

Accessing the Blueprint Pages

Select Data > Blueprints in the rail. Two views are available:

• Catalog (this page) — every blueprint of the configured catalogs, with install and re-apply actions.
• Installed — every blueprint installed on the active tenant, reached with View installed → (address .../repository/blueprints/installations).

Catalog View

The page title is Data; the header chip shows the number of blueprints (for example "32 blueprints"). The filter bar has:

Control	Purpose
All, Installed, Not installed, Updates	Status filter; each button shows the number of matching blueprints.
All Catalogs	Limit the list to one catalog source (for example PublicGitHubBlueprintCatalog, LocalFileSystemCatalog).
Search...	Filter by blueprint name and description.
Refresh button (Refresh blueprint catalog)	Reload the catalogs.

Each blueprint is a card with

• the name,
• a version drop-down (choose which catalog version to install; not for service-managed blueprints, which show their installed version) and the catalog badge,
• the description (shortened),
• a status chip (Available for not installed blueprints, Installed, or (installed) next to the version) and
• the action button: Install (not installed) or Re-apply (installed). It is disabled while the card shows Blocked or while the compatibility check runs, see Blocked versions.

Blueprints marked Service-managed (for example System.UI.TenantCockpit, System.Identity.Bootstrap) are applied and kept up to date by the platform. They show Installed and Managed by service and have no action button.

Installing a Blueprint

1. Find the blueprint in the catalog. Use search / filters as needed.
2. Choose the version in the drop-down if needed and click Install on the card.
3. The dialog Install blueprint asks Install blueprint '<id>-<version>' on this tenant? CK model dependencies and seed data will be imported. Confirm with Yes, or cancel with No.
4. While the apply runs the card shows a spinner. The action is locked until the apply finishes.
5. On success a green toast appears: Installed <blueprint-id> — <N> seed file(s). If the apply produced warnings the toast appends (<n> warning(s)) and a details dialog opens automatically — see Reading Warnings below.
6. The card flips to INSTALLED and the action button changes to Re-apply.

Re-applying a Blueprint

Re-apply is the recovery path: it re-imports the seed data via upsert even though the blueprint is recorded at the same version. It restores what the blueprint owns; it does not undo what the tenant owns (see What Install, Update and Re-apply Keep). Use it when:

• You suspect seed entities were modified or partially deleted and you want them re-asserted.
• A previous apply landed seed entities but did not finish the history insert (legacy behaviour, fixed in the per-tenant storage rollout — see the tech guide).

The flow is identical to Install but the dialog Re-apply blueprint reads Re-apply blueprint '<id>'? Existing seed entities will be upserted. "Upserted" does not mean that every value is reset: values that your tenant owns are kept.

What Install, Update and Re-apply Keep

A blueprint update or re-apply replaces the entities of the blueprint with the seed, but it never silently erases what was entered in your tenant:

• Values your tenant owns stay as they are. Examples: the enforcement mode of a data policy, the configuration of an adapter (including its credentials), the state of a stream-data archive. The seed only sets them when the entity is first created.
• A seed that is empty does not clear a filled value. If a new blueprint version would blank a value that is filled in your tenant, the update keeps your value and reports it as a warning.
• Entities the blueprint hands over to the tenant (a default template, an example rule) are created once. Later updates do not change them, and they do not come back after you delete them.
• Entities the blueprint owns (the locked ones) are renewed from the seed. Edit them only through the blueprint, or release them first.

Studio always applies with these defaults, so an update from Studio never blanks a value. Studio does not list the values an update would keep yet; before updating a tenant with entered data, run octo-cli -c PreviewBlueprintUpdate for the list. The rules in detail: Blueprint Ownership.

Reading Warnings

If the backend returned warnings during apply, the success toast appends a count and a details dialog opens automatically:

• Title — Blueprint apply warnings — <blueprint-id>
• Body — one bullet per warning, monospaced (whitespace preserved).
• Actions — Copy to copy the full list to the clipboard; Close to dismiss.

The dialog is resizable and non-blocking — the catalog refresh runs underneath while the dialog is open.

If a warning is unclear, copy the text and check the asset-repo logs for the corresponding ERROR / WARN entry around the timestamp of the apply.

Blocked versions

Before you click, Studio asks the server whether the CK models of the shown blueprint version would break a model that is already installed on the tenant (for example because an installed model is pinned to Basic-2.4.0 and the blueprint brings Basic-2.5.0). This is the tenant upgrade guard, the same check as on the Model libraries page. It applies to install, re-apply, update and downgrade, and to the first install as well. Studio has no force action: forcing a breaking update is an operation of the octo-cli and the API for data model managers.

• Checking compatibility… — while the check runs the action is disabled (its tooltip says so), so a button is never enabled before the answer is in. On the catalog, a card is checked when it comes into view or when you pick another version.
• Blocked — a red Blocked badge appears (on the card next to the status chip, on the details page in the header chips), the action is disabled and its tooltip names the first reason. On a card, Why? expands the list of blockers (Hide details collapses it); on the details page the list is shown below the summary. Each blocker names the blocked model (the installed model that would break), the update that causes it, the pinned dependency, required range or element concerned and, when the catalogs offer a newer version of the blocked model that resolves it, How to resolve. Resolve the blockers (update the blocked model first), then reload the page.
• Cannot check this update — if the check itself fails (network, permissions, server error) the action stays disabled with that reason and Retry runs the check again.

An older asset repository does not report blockers; the pages then look and work as before.

If the server still refuses an install or update (for example because the page was open for a while and the tenant changed meanwhile), the dialog Update blocked opens instead of a red error toast. It says that the request was refused and lists the same blockers. Close leaves it; the card or page then shows the Blocked state.

Failure Modes

Symptom	Cause
Red toast Install failed: <message>	Backend rejected the apply. The message often carries a hard conflict, a missing CK dependency, or a YAML schema error.
Dialog Update blocked, red badge Blocked	The server refused the request: it would break an installed model. See Blocked versions.
Spinner stays forever	Network or backend stall. Reload the page; the apply may have completed server-side already.
Card stays on NOT INSTALLED after success	Stale cache. Open View installed → to confirm; the catalog re-fetches on page enter.

Installed View

View installed → opens the page Installed blueprints with the number of installed blueprints (for example "11 installed") and a summary such as "11 root · 0 transitive deps". ← Browse catalog goes back to the catalog. The table has the columns:

Column	Meaning
Blueprint	Name of the blueprint.
Installed	Installed version, Root (requested explicitly) or Dependency (installed to satisfy another blueprint), Service-managed where the platform owns it, and the time of the first apply.
Last updated	Time of the most recent apply (install, update, re-apply, rollback).
Status	For example Up to date.

The button Refresh installed blueprints re-fetches the list from the backend.

Apply History

The history view is a chronological log of every apply operation (Initial, Update, Rollback, Reapply, Uninstall) with timestamps, the previous version (for updates and rollbacks), and per-operation entity counts:

Column	Meaning
Applied at	UTC timestamp of the apply.
Blueprint	Name and version that was applied.
Mode	Initial / Update / Rollback / Reapply.
Previous version	The version that was installed before this apply (empty for Initial).
Created	Number of seed entities created.
Updated	Number of seed entities updated.
Deleted	Number of seed entities deleted.

History is append-only — there is no edit/delete in the UI. The retention is per-tenant: when a tenant is deleted, its history goes with it.

Where the Data Lives

Both the installation rows and the history entries are stored as Construction Kit entities in the tenant's own runtime repository — there is no central registry. This matters in practice for two scenarios:

• Tenant backup — mongodump --db=<tenant> captures the blueprint state along with the seed entities.
• Tenant deletion — dropping a tenant deletes the blueprint history along with it. There is no "ghost history" left in a system database.

See Also

• Blueprints (Tech Guide) — full mechanics, schema, lifecycle
• Blueprint Ownership — what an update keeps, the preview and the confirmation
• octo-cli — ListBlueprints and related blueprint commands (Install / Update / Rollback / Uninstall) — the same operations from the command line