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

> ## Agent Instructions
> These docs contain multiple Speckle product experiences. For Speckle 2026.9, prefer /next/ pages for the topics and changes they cover. The navigation label Current does not override this version-specific precedence.
> Coverage under /next/ is incremental. Use Current documentation for unchanged topics and when a /next/ page says coverage is unavailable or explicitly refers you to Current. Do not infer a feature was removed from a missing page.
> Read the page-specific documentation status, applicability, affected guidance and replacement links in agent-only content. Impacted, changed and superseded apply only to the stated scope; they do not mean the entire feature is deprecated. Historical connector guides apply only to the legacy connector described.
> Match guidance to the customer's deployment version, model data format and connector. Respect plan, permission and compatibility restrictions. If an unknown version or data format changes the answer, ask a focused clarification; do not infer deployment version from the date alone.

# Common workflows

> Step-by-step guides for quantity takeoff, share of total, version comparison, validation, portfolio analysis, calculated fields, presenting to clients, and Context site maps.

Pick a goal below and follow the steps. Each workflow assumes you're in the dashboard editor and can add widgets from
the sidebar. For concepts and widget choices, see [Dashboards](/analytics/intelligence-dashboards). Not sure which
widget to add? See [Choosing the right widget](/analytics/intelligence-dashboards#choosing-the-right-widget) on the
Overview.

## Choose validation widgets

Use [Validation Widgets in Dashboards](/analytics/dashboards/validation-widgets)
to choose between dashboard-based validation
widgets and checks-and-standards Data Validation.

## Run a quantity takeoff

**When to use:** One model; you need element counts and optional area or length totals (e.g. for cost or schedule).

<Steps>
  <Step title="Load your model">
    Drag **Model Viewer** onto the canvas. Select your project and model; pin a version if you need
    a specific state.
  </Step>

  <Step title="Add Element count for total elements">
    Drag **Element count** onto the canvas. It shows the total count; use page-level filters to
    filter by level, category, or family.
  </Step>

  <Step title="Add a breakdown widget">
    Add **Total property value** for area/length sums or **Count by property** for counts by
    Category, Type, or Family (Revit: **Categories**, **Types**, **Families**). On Total widgets,
    open **Settings** and set **Aggregation** to Sum, Average, Min, Max, or Median. Use **Rounding**
    and, for area properties, **Display unit** if you need a different area unit on the chart.
  </Step>

  <Step title="Filter the dashboard">
    Click a value in any chart or table to filter the whole dashboard (e.g. one level, one
    category).
  </Step>

  <Step title="Browse elements in a table">
    Add **Element table** to see rows; customise columns, filter, and sort. Filter state is saved
    with the dashboard.
  </Step>
</Steps>

Outcome: Counts and breakdowns tied to the 3D model; filter state saved with the dashboard.

<Tip>
  On 2026.9, you can ask for a priced takeoff in plain language instead — see [Take off quantities
  and cost with Speckle Intelligence](/next/workflows/take-off-quantities-with-intelligence).
</Tip>

## Show each element's share of the whole

**When to use:** You already have a number on each element (for example area or length)
and you want each one’s share of the project total — as a fraction or percentage — for
tables, charts, or filters.

This uses two [calculated fields](/analytics/dashboards/calculated-fields): an
**Aggregate** for the total, then **Arithmetic** to divide each element’s value by that
total.

<Steps>
  <Step title="Load your model">
    Drag **Model Viewer** onto the canvas and select the project and model. Apply any page-level
    filters you want the “whole” to respect.
  </Step>

  <Step title="Create an Aggregate field for the total">
    Open **Calculated Fields**, click **New calculated field**, and choose **Aggregate**. Pick the
    number property (for example area), choose **Sum** (or another operation), and set the
    population: **All data** for a fixed project total, or **Current view** if the total should
    follow dashboard filters. Save and keep the field on this dashboard.
  </Step>

  <Step title="Create an Arithmetic field for the share">
    Create another calculated field and choose **Arithmetic**. Write a formula such as `a / b` (or
    `(a / b) * 100` for a percentage). Bind `a` to the element property and `b` to your Aggregate
    field. Save.
  </Step>

  <Step title="Show the share in a table or chart">
    Add **Element table** or a chart widget and pick the Arithmetic field as a column or value. You
    can also filter or colour by it.
  </Step>
</Steps>

Outcome: Each element has a share of the chosen total, without changing the model. The
Aggregate value is the same on every element — that is expected; the Arithmetic field
is what varies per element.

<Tip>
  Use Aggregate + Arithmetic for shares. An **All data** or **Current view** Aggregate field in a
  **Ratio** widget can inflate the result. See [Things to watch out
  for](/analytics/dashboards/calculated-fields#things-to-watch-out-for).
</Tip>

For comparisons between two models, use [Dashboard constants](/analytics/dashboards/calculated-fields#dashboard-constants).
To correct area units, create a **Unit conversion** field and use it in both calculations.

<div id="show-an-x-per-y-number-from-two-models" />

## Compare totals from two models

**When to use:** You want one intensity figure that mixes two models — for example power
load per square metre of IT room, desks per floor area, or people per workplace — and
you want that figure to remain fixed when someone filters the charts.

This uses [dashboard constants](/analytics/dashboards/calculated-fields#dashboard-constants)
in **Calculated Fields** (Aggregate → **Population** → **Dashboard constant**).

<Steps>
  <Step title="Load both models">
    Add a Model Viewer for each model so both appear on the dashboard — for example an equipment or
    rack model and a rooms or architecture model.
  </Step>

  <Step title="Create the comparison constants">
    Open **Calculated Fields**, create an **Aggregate** field, and set **Population** to **Dashboard
    constant**. Example: Sum of rack IT load from one model, and Sum of IT room area from the other.
    Pick a property that belongs to the model you mean, so the other model does not get mixed in by
    accident.
  </Step>

  <Step title="Show the comparison">
    Add a **Ratio Value** widget and pick those two constants as the two sides of the ratio (load ÷
    area). Or create an **Arithmetic** field that only uses those constants (for example `a / b`).
  </Step>
</Steps>

Outcome: One clear intensity figure such as load per m². It does not change when
people filter the dashboard. For limits and safer Ratio patterns, see
[Dashboard constants](/analytics/dashboards/calculated-fields#dashboard-constants).

## Compare two versions of the same model

**When to use:** You want to see what changed between two versions (e.g. before/after a design round).

<Steps>
  <Step title="Load both model versions">
    Add a **Dual viewer** and load both versions (first model / second model), or add two **Model
    Viewer** widgets and select the same project/model with different versions (pin each to a
    version).
  </Step>

  <Step title="Add widgets that support Compare mode">
    Add **Element count** or **Total property value** (or **Count by property**). In the widget's
    data source setting, select both viewers and choose **Compare** mode.
  </Step>

  <Step title="Synchronize the cameras">
    If you have two viewers side by side, turn on **Sync camera** in each viewer's sidebar so
    pan/zoom stays aligned.
  </Step>
</Steps>

Outcome: Side-by-side or compared counts and totals so you can see what changed between versions.

## Show a site model while analyzing design options

**When to use:** You want a site or existing-conditions model visible in the 3D view while charts and tables
tabulate only your design schemes (for example several Grasshopper-generated options).

<Steps>
  <Step title="Load the site and design schemes">
    Drag **Model Viewer** onto the canvas. Load your site model, then use **Add model** in the
    sidebar **Models** panel to add each design scheme.
  </Step>

  <Step title="Mark the site as a context model">
    Open the **⋯** menu on the site model row and choose **Use as context model**. The site stays
    visible when you filter the schemes in the viewer.
  </Step>

  <Step title="Connect widgets to design schemes">
    Add charts or tables (for example **Element count** or **Count by property**). In each widget's
    data source setting, select only the design scheme data sources—not the site model.
  </Step>

  <Step title="Filter and compare schemes on the canvas">
    Click values in charts to add page-level filters. The site model remains fully visible in the
    viewer while filters isolate objects in your schemes.
  </Step>
</Steps>

Outcome: Site geometry for spatial context in the 3D view; counts and breakdowns driven only by the schemes you
connect to analysis widgets.

## Perform portfolio analysis

**When to use:** Multiple projects or models; you want combined totals or differences across them.

<Steps>
  <Step title="Load the projects or models">
    Add a **Model Viewer** for each project (or key model) and select project/model for each.
  </Step>

  <Step title="Add widgets that support multiple data sources">
    Add **Element count** or **Count by property** and connect them to several viewers (use the
    widget's data source setting).
  </Step>

  <Step title="Choose Aggregate or Compare mode">
    Use **Aggregate** mode to see combined totals across models; use **Compare** mode to see
    differences.
  </Step>

  <Step title="Group widgets with sections">
    Add **Section** widgets to group areas (e.g. by project or by metric).
  </Step>

  <Step title="Share the dashboard">
    Share via [workspace access](/workspaces/roles-and-seats). Stakeholders see the same layout and
    data.
  </Step>
</Steps>

Outcome: One dashboard for portfolio-level counts and comparisons; stakeholders see the same view.

<Tip>
  On 2026.9, if you want to compare one project against a benchmark library rather than watch
  several live projects at once, see [Benchmark a project against your portfolio with Speckle
  Intelligence](/next/workflows/benchmark-against-your-portfolio-with-intelligence).
</Tip>

## Run a quick validation check

**When to use:** You want to check one or more properties against a rule (e.g. "doors must have fire rating") and see
pass/fail in the dashboard.

<Steps>
  <Step title="Load your model">
    Drag **Model Viewer** onto the canvas and select project and model.
  </Step>

  <Step title="Add Property checker">
    Drag **Property checker** from the Basics group. In the widget settings, choose the property and
    define the rule (e.g. "exists", "equals", "matches pattern").
  </Step>

  <Step title="View results and colorize the model">
    The widget shows pass/fail counts. Use the widget option to colorize the 3D viewer so you can
    see which elements pass or fail.
  </Step>

  <Step title="Add a reusable ruleset">
    For many rules or reusable rulesets, add **Model Validation** and define or import a ruleset.
    See [Data Validation](/analytics/data-validation/overview).
  </Step>
</Steps>

Outcome: Pass/fail view for one property (Property checker) or a full ruleset (Model Validation); optional
colorization in the viewer.

## Find models that use a specific family or type

**When to use:** You need to identify which models or elements use a given family (or category/type) so you can fix
or flag them (e.g. auditing families, pre-upgrade checks).

<Steps>
  <Step title="Add a model breakdown widget">
    Load the model(s). Use **Model structure** or **Families** (Revit) or **Count by property** to
    see family/category/type.
  </Step>

  <Step title="Search or filter by family name">
    Use the widget to search or filter by family name (or category/type).
  </Step>

  <Step title="Use Matches pattern in a filter">
    Add a filter with **Matches pattern** (e.g. family name `*ProblemFamily*` or `%ProblemFamily%`)
    to find matches.
  </Step>

  <Step title="Save a reusable validation rule">
    To flag this family in future, add **Property checker** or **Model Validation** and define a
    rule. See [Data Validation](/analytics/data-validation/overview).
  </Step>

  <Step title="Pin the model version">Pin the model version so the result is reproducible.</Step>
</Steps>

Outcome: List or count of models/elements using that family; path to validation if you want rules.

## Turn model codes into clear labels for charts

**When to use:** The model stores short codes (classification, type, zone, and similar),
and you have a spreadsheet that maps each code to a clearer name. You want charts,
filters, and colour-by in plain language — without changing the published model.

This workflow uses [Lookup tables](/analytics/dashboards/lookup-tables) and a
[Calculated fields](/analytics/dashboards/calculated-fields) **Map lookup**. If you only
need maths, unit changes, or simple groups (and no spreadsheet), skip the table and
create a calculated field of another type instead.

<Steps>
  <Step title="Load your model">
    Drag **Model Viewer** onto the canvas and select the project and model.
  </Step>

  <Step title="Create a Map lookup calculated field">
    Open **Calculated Fields**, click **New calculated field**, and choose **Map lookup**. Pick the
    model property that holds the code. Import your CSV or Excel list from the dialog (**Import new
    table** if tables already exist), or choose a table you already imported. Set the match column,
    the return column, and a fallback for codes not in the list. Save the field and make sure it is
    on this dashboard.
  </Step>

  <Step title="Chart or list by the new label">
    Add **Count by property**, **Total value by property**, or **Element table**. In the widget
    settings, pick your calculated field instead of the raw code property.
  </Step>

  <Step title="Filter or colour the model">
    Use the calculated field in a filter, or colour the viewer by it, so stakeholders see the
    friendly labels rather than the codes.
  </Step>

  <Step title="Add further calculated fields">
    Need areas in another unit for filters or further maths? Add a **Unit conversion** field, then
    build on it. For chart labels only, use widget **Display unit** instead (see [Aggregation and
    numeric display](/analytics/intelligence-dashboards#aggregation-and-numeric-display)). Need
    pass/fail-style labels for a table column? Add a **Logical** field. See [Calculated
    fields](/analytics/dashboards/calculated-fields).
  </Step>
</Steps>

Outcome: Charts and filters use clear labels from your list; the model itself is
unchanged. Update the lookup table later when the list changes — fields that use it
pick up the new rows when the dashboard reloads the data.

## Present a dashboard to a client

**When to use:** You want to share a read-only view or embed the dashboard in a presentation (e.g. Notion, Miro).

<Steps>
  <Step title="Arrange the layout and apply a theme">
    Resize and reorder widgets; add **Section** widgets to group content. In the **Themes** panel,
    pick a built-in or custom theme so chart and validation colors stay consistent. See
    [Layout](/analytics/dashboards/layout#themes) for scopes and editing.
  </Step>

  <Step title="Use the view link">
    Share the dashboard **view** link (not the edit URL). Recipients always open in **presentation
    mode** — view mode and shared mode are the same read-only experience. See
    [Sharing](/analytics/dashboards/sharing) for share links and presentation mode.
  </Step>

  <Step title="Embed the dashboard">
    You can embed dashboards in Notion, Miro, and other tools. For step-by-step guides, see
    [Tutorials](https://speckle.systems/tutorials) (filter by **Dashboards & Insights**).
  </Step>
</Steps>

Outcome: A shareable or embeddable dashboard in presentation mode, with a clear layout
and theme.

## Show your model on a map with Context (beta)

**When to use:** You want to place a Speckle model on a pitched 3D map at a real-world site.
Models do not need geographic metadata.

**Context** (beta) is the Presentation widget that draws Speckle geometry on OpenFreeMap at the
dashboard site location. It is not the same as marking a model as a
[context model](/analytics/intelligence-dashboards#context-models) in the Model Viewer.

<Note>
  This workflow adds a Model Viewer, Context, and optionally Map to the same dashboard — each uses
  one or more browser rendering contexts. On a dashboard that already has several viewer or map
  widgets, you can hit your browser's limit. See [3D viewer widget
  limit](/analytics/dashboards/layout#is-there-a-limit-to-how-many-3d-viewer-widgets-i-can-add).
</Note>

<Steps>
  <Step title="Load your model">
    Drag **Model Viewer** onto the canvas and select your project and model. Context reuses geometry
    from an existing viewer on the dashboard when one is available.
  </Step>

  <Step title="Add Context">
    Drag **Context** from **Presentation** onto the canvas. The widget panel shows a **Beta** badge.
  </Step>

  <Step title="Set the dashboard site location">
    In the Context sidebar, open **Site** and enter latitude and longitude (optional elevation and
    rotation). Select **Apply** to save the placement. The site location is owned by the dashboard —
    you do not need geographic data on the model. You can also set the site from a **Map** widget;
    both share the same site.
  </Step>

  <Step title="Add a map for location pins">
    Drag **Map** from **Presentation** if you want a lighter map with location bookmarks only (no
    Speckle geometry). Search for a place, then add, rename, or remove pins from Locations.
  </Step>

  <Step title="Tune filters, colour, and the map">
    Use Context sidebar controls as needed: local **Filters**, **Apply global filters**, **Apply
    color by**, and **Include nested objects** (same idea as Model Viewer). Save a starting
    viewpoint with **Focus** or Camera → Save current. Use the bulldozer control to hide basemap
    buildings that overlap the model; set **Building clearance** and optionally **Show clearance
    boundary**. **Clip model to ground** hides Speckle geometry below the map surface (on by
    default).
  </Step>
</Steps>

Outcome: Context shows your Speckle model on a pitched 3D map at the dashboard site. Map (if
used) shows site markers and optional pins only.

The **Map** widget shows site markers and location pins. Use **Context** to show model geometry
on the map. The Model Viewer keeps its local coordinates. Context also saves location bookmarks
and a starting camera position.

<Warning>Context is beta. Avoid relying on it for production-critical dashboards.</Warning>

Map tiles require an internet connection, and OpenFreeMap attribution stays visible. Deleting a
Map or Context widget does not clear the dashboard site location.

## See also

* [Filters](/analytics/dashboards/filters) — Filter levels, operators, and colorizing the model
* [Calculated fields](/analytics/dashboards/calculated-fields) — Add your own values for charts, filters, and colour-by
* [Calculated fields — Dashboard constants](/analytics/dashboards/calculated-fields#dashboard-constants) — Stable totals and X-per-Y numbers from two models
* [Lookup tables](/analytics/dashboards/lookup-tables) — Import lists for Map lookup and validation
* [Layout](/analytics/dashboards/layout) — Resize widgets and themes
* [Sharing](/analytics/dashboards/sharing) — Share links, present mode, scenarios, and
  embedding
* [Validation Widgets in Dashboards](/analytics/dashboards/validation-widgets) — Sub-guide for dashboard-based validation widget workflows
* [Data Validation](/analytics/data-validation/overview) — Property checker, Model Validation, and rulesets
* [Dashboards — Widget groups](/analytics/intelligence-dashboards#widget-groups-in-the-sidebar) — Full Presentation widget list including Map and Context


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.