Exporting and uploading models from Revit

This guide walks Revit add-in users through the three export commands on the Alpha → Export ribbon panel, what each one uploads, where the files end up, and how variants work end-to-end.

TL;DR — pick the right button

The join key for all three commands is the Revit group name. Name your groups exactly as the backend expects (e.g. ASRR_CORE-T1_DK_TW_5400_Langskap_Dakkapel) — that name is matched verbatim against the type's product catalogue.

If a group name doesn't match anything in the catalogue, the file is exported to disk only and a warning is shown. Use Tools → Missing Coverage to find unmatched groups before exporting.

Naming convention

Backend product names are built from the type's concept and name fields plus a Dutch domain suffix:

<concept>_<typeName>_<rest of the productName>
ASRR_CORE-T1_DK_TW_5400_Langskap_Dakkapel
└──┬─┘ └──┬──┘ └──────────┬──────────┘
concept  type        productName tail

Real examples from production:

• ASRR_CORE-T1_ACH_BG_TW_5400_Geen — achtergevel begane grond, tweekapper, 5400mm, geen kozijn
• ASRR_CORE-T1_DK_TW_5400_Langskap_Dakkapel — dakkapel, tweekapper, 5400mm, langskap
• ASRR_CORE-T1_Casco_HW_5400_Langskap_disable — casco, hoekwoning, 5400mm, langskap (disabled-variant marker)

The first two _-separated parts (ASRR + CORE-T1) decide which type owns the product. The picker dialog (see below) reads those parts to auto-pick the type for you.

Export As Project Variants — the picker dialog

When you click Export As Project Variants, a dialog opens before any export runs:

1. Type — auto-detected from the first selected group's concept_name prefix. Falls back to the previously-saved type, then the first available.
2. Project — defaults to the previously-saved project. Pick the right one before clicking confirm; the dropdown shows the project name as it appears in Alpha (e.g. "Poeldonkweg 55, 5216JX 's-Hertogenbosch").
3. Selected groups — read-only preview of what will be exported. Use it to spot-check before committing.

When you click Export and upload, the picker:

• Saves your Type and Project as the new defaults (so the next session pre-fills correctly).
• Calls GET /projects/{projectId}/types/{typeId}/models to fetch that project's catalogue.
• For each selected group, looks up the group name in the catalogue and routes the upload accordingly (see next section).

Auto-routing rules

The catalogue returns two kinds of entries — CONCEPT models (per-project overrides) and variant facade models (per-variant facades). Routing per group:

For CONCEPT matches, the override row holds GLB+RVT+PNG together; re-uploading a file with the same extension replaces the previous blob (the old blob is deleted). The type-product-coverage row for that name stays untouched.

For variant matches, the variant-templated productName is what the row's identity is at the type level — so multiple projects that use the same variant share these files.

Where to verify your uploads

After running an export, open Alpha in your browser to confirm the files landed where you expected.

Type-level coverage (Export Selected Groups, Export Visible in View, variant facades)

Page: Type editor → Statistics tab → Coverage view
URL: /types/editor/{typeId}?typeEditorView=statistics&statisticsView=coverage
Source file: src/frontend/src/domains/construction/types/type-editor/screens/statistics/type-statistics-dashboard.tsx

You'll see a table of every coverage row for the type with badges per asset (RVT / GLB / PNG) and a complete indicator. Hovering shows a thumbnail + 3D preview.

Project concept overrides (Export As Project Variants → CONCEPT match)

Page: Project editor → Models view → Concept tab
URL: /projects/{projectId}/editor?view=models&modelsTab=concept
Source file: src/frontend/src/domains/construction/projects/project-editor/screens/models/concept-model-overrides-table.tsx

The override appears as a row with treeId, conceptModelName, and an asset breakdown. All three files (GLB, RVT, PNG) you uploaded sit on the same row.

Project variants management (defining variants, name overrides)

Page: Project editor → Models view → variant tab (one tab per variant)
URL: /projects/{projectId}/editor?view=models&modelsTab={variantId}
Source files:

• …/screens/models/variant-manager.tsx — create/edit/delete variants
• …/screens/models/variant-name-overrides-table.tsx — generated → override name mappings

This is where you define the project's variants and the per-variant productName overrides that the variant-templating uses at runtime.

Live 3D viewer (consumes whatever you uploaded)

Page: Buyer-configuration viewer for a specific house
URL: /projects/{projectId}/editor/{scenarioId}/{blockId}/{houseId}/{configurationId}/viewer
Source file: src/frontend/src/shared/components/canvas/configurator/house/HouseViewer.tsx

Resolves each model with the precedence: project override (CONCEPT only) → variant-matched type-coverage → fallback type-coverage. If your override worked, you'll see your new GLB here; if it didn't, the viewer falls back to the type's shared GLB.

How variants work, end-to-end

Variants are how a project says "my houses come in flavour A or flavour B" — typically a facade style or a layout variation that affects the visual model but not the underlying type.

1. Type definition. The type's staticModels list contains static model trees tagged either CONCEPT (the same model in every project) or PROJECT (a placeholder that gets resolved per-variant). The type maintainer creates these in the Type editor → Static Models view.
2. Project variants. Each project defines its own list of variants — { id, name, typeId } — through the Project editor → Models view's variant manager. Variant names are short slugs (modern, klassiek, langskap).
3. Variant-templated product names. For PROJECT-type trees, the backend resolves the placeholder name into a variant-specific name using staticModelService.resolveVariantTemplate. So a placeholder ASRR_CORE-T1_VG_BG_TW_5400_{variant} becomes ASRR_CORE-T1_VG_BG_TW_5400_modern for the modern variant, …_klassiek for the klassiek variant, etc.
4. House → variant. Each house in the project has a variantId referencing one of the project's variants. The Sales view on the project editor lets a real-estate seller assign or change a house's variant.
5. Runtime resolution. When a buyer-configuration is opened in the viewer, the backend walks each static model tree:
   • CONCEPT trees look up the type's coverage row by the resolved productName. If a project override exists, it wins.
   • PROJECT trees look up the type's coverage row by the variant-templated productName. The variant facade row found there is what gets rendered.
6. Where the Revit upload lands. When you run Export As Project Variants on a group named …_modern, the picker fetches the project's catalogue, sees …_modern in the variant models list (PROJECT type), and routes the upload to the type-coverage row for …_modern. Every project that has a modern variant will pick this up automatically.

The shape lives in ProjectModelsResponse (/projects/{id}/types/{typeId}/models) — useful if you ever want to inspect the catalogue from a curl:

{
  "typeId": "AAABnEyL2Vw_iKWo",
  "conceptModels":  [ /* CONCEPT models — match these names → project override */ ],
  "variants":       [ { "id": "…", "name": "modern" }, … ],
  "variantModels":  { "<variantId>": [ /* PROJECT models with variant-templated names */ ] }
}

Common issues

• "Doesn't match any project model — export only, no upload"
  The group name isn't in the project's catalogue for the picker's chosen type. Re-check the type in the picker (concept_name prefix) and confirm the productName exists at …/types/editor/{typeId} → Statistics. If the product is on a different type, change the picker's type dropdown.

• "GLB shows in viewer but not in the type-coverage UI"
  Expected behaviour for project overrides — the GLB lives on the project, not the type. Check Project editor → Models → Concept to see it.

• "My RVT/PNG didn't appear on the type-coverage row"
  If you used Export As Project Variants and the group matched a CONCEPT model, all three files went to the project override (since 3.268.0). Use Export Selected Groups if you want to publish at the type level instead.

• "Picker dropdown shows the wrong project as default"
  The default is the last project you confirmed, persisted in ~/Alpha/settings.json under ProjectId. Pick the right project once and the next run will remember it.

Quick reference of endpoints