Skip to main content

Getting Started

🚧 This page is under construction 🚧

Audience: technical evaluators, IT architects, and BIM managers.

1. What is VIM Server?​

VIM Server is a self-hostable BIM data platform. It runs entirely in your own Azure subscription - your models, your database, your storage, your tenant. It is unlocked by a license file.

The role of VIM Server is to turn BIM models into VIM files (a fast, compact 3D + data format) and structured Parquet data, keep them up to date automatically, and serve them to people and tools:

  1. Ingest - models come in two ways: direct VIM upload from the browser, or Autodesk Forma Revit sources converted in the cloud (via the Autodesk Design Automation API).

  2. Convert & merge - each source becomes a VIM file; the server merges a project's sources into a single project VIM, on demand or on a schedule (cron presets, auto-merge when sources complete).

  3. Publish - every merge also produces a set of Parquet files (one per entity table - elements, parameters, geometry summaries, and so on), which is what Power BI and SQL queries consume.

  4. Serve - through a web UI with a 3D viewer, Power BI connectivity, a versioned REST API, and an MCP server for AI tools.

2. Capabilities​

Web UI​

A Blazor web application - the operational front end of the platform:

  • Organizations, projects, members - team management with per-project roles (Viewer / Manager).

  • Sources & scheduling - add VIM-upload or Autodesk (ACC) sources; assign org-level schedule presets; runs and merges trigger automatically and report live progress.

  • 3D viewer - view any VIM file directly in the browser (WebGL), as a dialog or a standalone page.

  • Run history, jobs, storage - inspect every conversion and merge, manage blobs and Parquet output.

  • Administration - license management, users, Autodesk credentials, query/timeout settings, all gated behind a Root Administrator role.

Power BI connectivity​

Project data is analytics-ready without an ETL pipeline of your own:

  • Every merge writes a Parquet bundle (~60 files, one per entity table) alongside the merged VIM.

  • A shipped Power BI report template (pbi/) reads Parquet straight from the REST API. A report author sets two parameters (server URL, project ID) and one credential (a Personal Access Token) - no per-report plumbing.

  • The template includes an embedded 3D VIM viewer visual, so reports combine tabular analytics with the model itself.

  • Reports refresh against the user's live permissions - losing access to a project immediately stops its reports from refreshing.

REST API​

A versioned JSON API under /api/v1 for automation and integration (the same API Power BI uses):

  • Identity & discovery - profile, organizations, projects, per-project detail.

  • Run control - trigger project runs and merges, cancel in-flight work.

  • VIM transfer - upload source or merged VIMs (two-phase, direct-to-storage via short-lived SAS), download any version via signed URLs.

  • Parquet - manifest + per-file download of a project's Parquet data.

  • Project data - a namespace/key/value store per project, designed to join custom rows (e.g. per-element costs) against the VIM element table in Power BI.

  • Metrics - read aggregate content metrics per snapshot, and manage the metric definitions that compute them.

  • Query sessions - open a session, load one or more project snapshots, and run ad-hoc read-only SQL (DuckDB dialect) over their Parquet tables.

The full surface is documented by an OpenAPI specification served at /openapi/v1.json (authentication required).

MCP server​

An MCP (Model Context Protocol) server at /mcp (streamable HTTP) lets AI assistants and agentic tools work with your BIM data directly:

  • Discovery tools - list organizations, projects, members, sources, and snapshots.

  • Metrics tools - read metric values and create/edit/test the metric definitions behind them.

  • SQL tools - a one-shot project_sql_run for quick questions, plus multi-query session tools that load several snapshots (even across projects) and query them together.

  • Schema tools - retrieve the Parquet schema documentation so a client can write correct SQL.

MCP calls authenticate with the same Personal Access Tokens as the REST API and are authorized against the same per-user permissions - an AI client can only see what its user can see.

3. Authentication & authorization​

Every caller presents a credential suited to its channel:

  • People (web UI) - sign in with Microsoft Entra ID (OIDC, single-tenant, secretless app registration); a cookie session follows. A Root Administrator Entra app role grants system administration.

  • REST API & MCP clients - an Entra JWT or Personal Access Token in one Authorization: Bearer header. PATs (vim_pat_...) are generated in the UI, shown once, stored only as a SHA-256 hash, and act as their owning user - never as root.

  • Power BI - the user's PAT as a Basic credential. One credential per data source; every request is re-authorized against the user's live project access. Use a service-account user's PAT for shared dashboards.

  • Power BI embedded viewer - a per-project view token (vim_view_...) baked into the Parquet output. View-only: it can download the project's VIM for display but is rejected by every data endpoint. Rotatable by an org admin.

  • Cloud job runner - an internal machine API key held in Azure Key Vault. Never leaves your Azure environment.

Authorization is role-based and evaluated per request:

  • Organization roles - admin or member. Org admins manage every project in the org.

  • Project roles - projects are members-only: Viewer (read, download, view) or Manager (Viewer + settings, members, sources, triggering runs).

  • Root Administrator - system-level administration (license, users, server settings), assigned as an Entra app role in your tenant.

The entire application (UI and API) is license-gated: the server stays locked until a valid VIM Server license file is installed by a Root Administrator.

4. Architecture​

Everything inside the your Azure subscription box is provisioned by the deploy tooling (.NET Aspire) into a single Azure resource group.

                    Users and integrations
  +-----------+  +-----------+  +-----------+  +-----------+
  |  Browser  |  |  Power BI |  |   REST    |  |  AI tools |
  | (UI + 3D) |  | (reports) |  |  clients  |  |   (MCP)   |
  +-----+-----+  +-----+-----+  +-----+-----+  +-----+-----+
        |              |              |              |
        +--------------+-----+--------+--------------+
                             | HTTPS
+----------------------------+---------------------------------------+
| your Azure subscription    v                                       |
|           +--------------------------------------+                 |          External services
|           |         VIM Server web app           |                 |      +----------------------+
|           |        (Azure Container App)         |-----------------+----->|  Microsoft Entra ID  |
|           |   Blazor UI | REST API | MCP server  |-----------------+--+   |      (sign-in)       |
|           +------+------------+------------+-----+                 |  |   +----------------------+
|                  |            |            |                       |  |
|      starts jobs |   metadata |            | read-only SQL         |  |   +----------------------+
|                  v            v            v                       |  +-->|  Autodesk Platform   |
|     +---------------+  +--------------+  +---------------------+   |      |  Services (cloud     |
|     | Cloud Job     |  | PostgreSQL   |  | Query Runner        |   |      |  Revit conversion)   |
|     | Runner        |  | Flexible     |  | (Container App,     |   |      +----------------------+
|     | (Container    |  | Server       |  |  internal ingress,  |   |
|     |  App Job)     |  |              |  |  DuckDB engine)     |   |
|     +-------+-------+  +--------------+  +--------+------------+   |
|             |                                     |                |
|             | reads source VIMs, writes           | reads Parquet  |
|             | merged VIM + Parquet                | (signed URLs)  |
|             v                                     v                |
|     +-----------------------------------------------------------+  |
|     |        Azure Blob Storage  (VIM files, Parquet data)      |  |
|     +-----------------------------------------------------------+  |
|                                                                    |
|     Supporting: Key Vault (secrets), Container Registry (images),  |
|     Application Insights (optional telemetry)                      |
+--------------------------------------------------------------------+

The moving parts:

  • VIM Server web app (Azure Container App) - the core: Blazor UI, REST API, MCP server, scheduling, orchestration. The only component with public ingress.

  • Cloud Job Runner (Azure Container App Job) - on-demand worker for merges and cloud conversions; sized independently (up to dedicated high-memory nodes for large models) and scales to zero when idle.

  • Query Runner (Azure Container App, internal-only ingress) - sandboxed DuckDB engine for ad-hoc SQL over Parquet snapshots; reachable only from the web app, never from the internet.

  • PostgreSQL Flexible Server (Azure Database for PostgreSQL) - all metadata: organizations, projects, sources, runs, sessions, tokens. Sensitive values (e.g. Autodesk credentials) are stored as encrypted records. Optional zone-redundant HA and geo-redundant backup.

  • Blob Storage (Azure Storage account) - VIM files and Parquet data. Downloads use short-lived (hours) signed URLs minted per request - no long-lived storage credentials are handed out.

  • Key Vault (Azure Key Vault) - internal secrets, e.g. the machine API key the cloud job runner authenticates with.

  • Container Registry (Azure Container Registry) - holds the application images built by the deploy.

  • Application Insights (optional; your own instance) - durable logs/metrics/traces if you connect one; otherwise telemetry stays in the in-memory dashboard.

External dependencies are limited to Microsoft Entra ID (your tenant, for sign-in) and - only if you use Autodesk sources - Autodesk Platform Services (Design Automation, i.e. cloud Revit, for conversion). Everything else stays inside your subscription.