> ## 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.

# 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.

## Sub-guide: Validation widgets

Use [Validation Widgets in Dashboards](/analytics/dashboards/validation-widgets)
as a focused sub-guide when you need 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="Add a Model Viewer and select 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
    slice by level, category, or family.
  </Step>

  <Step title="Add Total property value or Count by property for breakdowns">
    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="Use page-level filters to slice">
    Click a value in any chart or table to filter the whole dashboard (e.g. one level, one
    category).
  </Step>

  <Step title="Optionally add Element table to browse or export">
    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.

## 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="Add a Model Viewer and 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>
  Prefer this Aggregate + Arithmetic pattern for shares. Putting an **All data** or **Current view**
  Aggregate field into a **Ratio** widget can inflate the number — see [Things to watch out
  for](/analytics/dashboards/calculated-fields#things-to-watch-out-for). For “X per Y” intensity
  figures from two models (for example power load per m² of room), use [Dashboard
  constants](/analytics/dashboards/calculated-fields#dashboard-constants) instead. If areas are in
  the wrong unit first, add a **Unit conversion** field and use that as the source for both the
  Aggregate and the Arithmetic bindings.
</Tip>

## Show an X-per-Y number 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 stay put when someone clicks filters on 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 one constant for each side of the comparison">
    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 jump around 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="Add a Dual viewer or two Model Viewers">
    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="Optionally sync the camera">
    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 site and schemes in one Model Viewer">
    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 scheme data sources only">
    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="Add a Model Viewer per project or key model">
    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="Use Sections to group by project or metric">
    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.

## 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="Add a Model Viewer and 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="For full rulesets, use Model Validation">
    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 Model structure or Families (Revit) or Count by property">
    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="For reusable rules, use Property checker or Model Validation">
    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="Optionally pin the dashboard 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="Add a Model Viewer and 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="Optionally add more 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="Optionally embed elsewhere">
    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.

<Steps>
  <Step title="Add a Model Viewer and 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). Apply commits placement. The site location is owned by the dashboard — you do not
    need geographic data on the model. You can also author Site from a **Map** widget; both share
    the same site.
  </Step>

  <Step title="Optionally add a Map for 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 deck (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.

<Info>
  The **Map** widget alone does not draw Speckle geometry — only the site marker and location pins.
  **Context** is the path for seeing the model on a map. The Model Viewer stays in local
  coordinates; Context handles the 3D-on-map view. Context can also keep its own Locations bookmarks
  and a saved starting camera.
</Info>

<Tip>
  Context is **beta**. Treat it as evolving — not for production-critical dashboards. Map tiles need
  an internet connection; OpenFreeMap attribution stays visible. Deleting Map or Context widgets
  does not clear the dashboard site location.
</Tip>

## 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