Table of Contents

Global Mapper User Guide

Global Mapper (GM) is a powerful tool for managing and replacing elements across your Revit project in bulk. Instead of manually swapping families, types, materials, or styles one by one, Global Mapper lets you plan and execute these changes all at once.

What is Global Mapper?

Think of Global Mapper as a "find and replace" tool for your Revit project, but much smarter. It can:

  • Replace families and types - Swap out one family or type for another across your entire project
  • Find duplicates - Identify similar elements that might be duplicates (like "Wall Type 1" and "Wall Type 1 Copy")
  • Manage materials - Replace one material with another wherever it's used
  • Handle line and object styles - Swap styling consistently throughout your project
  • Work with shared parameters - Add or map shared parameters to families and categories

The tool uses similarity matching to suggest the best replacement candidates, making bulk changes faster and less error-prone.

When to Use Global Mapper

Global Mapper is ideal for these common scenarios:

Scenario How GM Helps
Project cleanup Find and consolidate duplicate families, materials, and styles
Standards migration Replace legacy families/types with company-standard versions
Template updates Apply new material or style standards across the project
Family consolidation Merge similar families into one, reducing project bloat
Shared parameter rollout Add shared parameters to multiple families at once
Pre-handoff cleanup Standardize elements before project delivery

Quick Start

Get started with Global Mapper in 5 steps:

Step 1: Open Global Mapper

Click the Global Mapper button on the DBTools ribbon in Revit.

[Screenshot: GM button location on ribbon]

Step 2: Select Your Category

In the Families tab, use the category dropdown to select what type of elements you want to work with (Doors, Windows, Walls, etc.).

[Screenshot: Category dropdown]

Step 3: Find Elements to Replace

Browse the list of families in your project. Each row shows:

  • The family name (source)
  • The number of instances in your project
  • A dropdown to select what to replace it with (target)

[Screenshot: Family list with source and target]

Step 4: Select Targets

Click the dropdown in the Target column to see replacement options. Options are sorted by similarity - the best matches appear at the top with higher percentages.

Step 5: Review and Commit Changes

  1. Check the Apply checkbox for each mapping you want to make
  2. Click Review Plan
  3. GM opens Commit Review and shows the plan before any model edits
  4. Review plan sections and status:
    • Bottom status bar shows Rules and Families (single-line, pinned to the window bottom)
    • Failed Operations is summarized per mapping rule; Source/Target display names (not element IDs)
    • Operation Results section lists each operation row with status (Pending, Succeeded, Failed, Skipped), stable operation id, stage, and timing
    • Domain Summary section shows per-stage succeeded/failed/skipped counts, affected references, and family/timing context
    • Commit execution continues across failures; failed operations are recorded while remaining operations still run
    • Right-click report tables for Copy Selected / Copy All
    • Non-relevant sections are hidden so only applicable expanders appear
  5. Click Apply to execute the plan (changes are applied immediately)
  6. After apply completes, Commit Review stays open and shows results:
    • Click Rollback to roll back all applied changes (transaction-group rollback)
    • Click Accept + Continue to accept changes (assimilate) and return to GM
    • Click Accept + Close GM to accept changes (assimilate) and close GM
    • If nothing was applied and failures were detected, Commit Review switches to Retry Apply + Close
  7. During commit, the overlay Cancel button requests cancellation immediately
  8. Closing Commit Review with the window X:
    • During apply: triggers cancellation + graceful cleanup before the window closes
    • After apply (pending accept/rollback): prompts you to Accept + Continue, Accept + Close GM, or Rollback
  9. Banner feedback:
    • Success shows a green summary banner (Applied, Failed, Skipped)
    • Failure shows a red banner starting with Commit failed.
    • On failure, Commit Review stays open so you can inspect errors before deciding to retry/continue/close
    • Accept + Continue refreshes mapped data in-place (families/usage) and restores expanded row-details context

Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:4595
Source: src/Tools/Common/GM/Shell/Services/CommitReviewWindowService.cs:68
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:267
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:548
Source: src/Tools/Common/GM/Shell/Views/CommitReviewWindow.xaml.cs:44
Source: src/Tools/Common/GM/Shell/Views/CommitReviewWindow.xaml:111
Source: src/Tools/Common/GM/Shell/Services/CommitReviewWindowService.cs:61
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:274
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:327
Source: src/Tools/Common/GM/Shell/Views/CommitReviewWindow.xaml.cs:60
Source: src/Tools/Common/GM/Shell/Views/CommitReviewWindow.xaml:318
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.UsageAndFamilies.cs:236

The Global Mapper Window

When you open Global Mapper, you'll see a window with several main areas:

[Screenshot: GM main window with labeled areas]

Header Controls

Located at the top of the window, these controls affect all tabs:

Control What It Does
Search box Filter the list by name - type to find specific elements
Threshold slider Adjust how similar items need to be for auto-selection (0-100%)
Sort mode Toggle between "Similarity" (best matches first) or "Alphabetical"
Filters Show/hide items based on criteria like "Applied only" or "Hide unused". Some filters are tab-aware: "Applied Only" hides on Duplicates; "Hide Unscanned" shows only on Families and Shared Parameters

Bottom Status + Empty-State Feedback

  • The bottom-left status line is split into two live segments:
    • Global: Families/Usage/Shared Parameters readiness
    • Active: the currently selected tab's visible state
  • GM empty states are load-aware:
    • During first load, grids show explicit Loading... messaging
    • After load completes, zero-result states show contextual No ... messaging and guidance
  • Empty-state copy/contrast is theme-aligned for dark UI readability.

Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.CoreAndCommands.cs:867
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:4619
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:1469

Main Tabs

Global Mapper organizes your work into six tabs:

  1. Duplicates - Find and resolve potential duplicate elements
  2. Families - Map families and types to replacements
  3. Line Styles - Replace line styles
  4. Object Styles - Replace object styles
  5. Materials - Replace materials
  6. Shared Parameters - Manage shared parameter assignments

Tab Guide

Duplicates Tab

The Duplicates tab automatically finds elements that might be duplicates based on name and property similarity.

[Screenshot: Duplicates tab]

How to use it:

  1. Open the Duplicates tab; scanning runs automatically
  2. Use Category to scope family duplicate rows (it stays synced with the shell-wide category state)
  3. Use Kind to filter duplicate sources (All, Families, Materials, Line Styles, Object Styles, Shared Params)
  4. Use the tree filter bar (All / Open / Resolved / Excluded / Conflicts) to focus on groups by status
  5. Review tree rows by source component and pick a Keep Target per source row — tree nodes show aggregate resolved counts (e.g., "Families (133) · 45 resolved")
  6. Toggle Apply only for rows you want commit-ready now
  7. Optional: uncheck Save for one-time mappings (used for this commit run only)
  8. Optional (families): right-click a source row and choose Edit Type Mapping... to control source-type to keep-type mappings
  9. Use the inspector pane (right) for candidate details and actions: toggle Inspector Pane in the top bar
  10. In the inspector, use the Accept split button (primary action persists selection; dropdown Accept Once for session-only mapping)
  11. Expand the Metadata section in the inspector to see Source ID and Instance Count
  12. Click Accept Applied to stage only rows that are Apply=true and valid/ready
  13. Shared Parameter duplicate rows can drive Shared Parameters authoring selections (Map From + Apply) for commit

Understanding the columns:

Column Description
Apply Session-only commit intent flag (defaults off and is never restored from persisted state)
Source The element that will be replaced, plus metadata (Kind, Suggestions, Highest Score) shown inline
Keep Target Explicit source → keep decision (single target per source, constrained to same domain/category bucket)
Save Persist keep selection across sessions (off = one-time mapping for current run only)
Status Review state (Ready, Accepted, Mapped, or blank)

Readiness rules:

  • Ready requires Apply=true, non-self keep target, non-excluded row, and no validation/conflict flags.
  • Choosing self as Keep Target marks the row as keeper and forces Apply=false (no-op rows cannot commit).
  • Accept Applied uses readiness (member.IsReady) rather than raw Apply=true. The "Applied Only" filter is hidden on the Duplicates tab (the tree filter bar supersedes it).
  • Keep targets, one-time save choice, and exclusions persist by row key; Apply never persists.

Exclusion badges (Saved, Session, Saved (Overridden)) include a tooltip timestamp when ExcludedAt is available.

Conflict guardrails:

  • Blocking conflicts (commit-active) prevent Review Plan.
  • Advisory conflicts (restored-saved, not currently applied) still surface in the conflict flyout.
  • The bottom-right conflict button appears whenever blocking or advisory conflicts exist.
  • If one duplicate source is accidentally accepted to multiple targets, GM raises a duplicate multi-target conflict and provides one-click cleanup actions.
  • Choosing Keep Manual for a duplicate-vs-manual conflict clears the duplicate source row's keep/apply state, so the same duplicate conflict does not immediately reappear.

Source: src/Tools/Common/GM/Shell/ViewModels/DuplicatesModels.cs:59 Source: src/Tools/Common/GM/Shell/ViewModels/DuplicatesPaneViewModel.cs:373 Source: src/Tools/Common/GM/Shell/ViewModels/DuplicatesPaneViewModel.cs:538 Source: src/Tools/Common/GM/Shell/ViewModels/DuplicatesPaneViewModel.cs:1915 Source: src/Tools/Common/GM/Shell/ViewModels/MappingPaneViewModel.cs:44 Source: src/Tools/Common/GM/Shell/Services/MappingConflictService.cs:65 Source: src/Tools/Common/GM/Shell/Services/PlanBuildingService.cs:350

Families Tab

The Families tab is where you map families and their types to replacement targets.

[Screenshot: Families tab]

Main list columns:

Column Description
Expand (+) Click to see details (types, materials, parameters)
Quantity Number of instances of this family in the project
Apply Check to include this mapping when applying changes
Source The family name
Target Dropdown to select the replacement family

Working with families:

  1. Select a category from the dropdown at the top
  2. Find your source family in the list (use search to filter)
  3. Choose a target from the dropdown - options show similarity scores in color:
    • Green = High similarity (good match)
    • Orange = Medium similarity
    • Red = Low similarity
  4. Check Apply to include this mapping

Expanding family details:

Click the + button to see:

  • Types - Individual types within the family, with their own target mappings
  • Type creation flow - Use each type row's Create checkbox plus New Type Name field (there is no separate header-level New Type button)
  • Object Styles - Styles used by this family
  • Materials - Materials used by this family
  • Parameters - Parameter name mappings (with example values). Rows are split by scope: (Instance) and (Type).
  • Conflicts (Parameters) - If GM detects a parameter conflict (duplicate target parameter or required type-write policy), the family row and/or parameter rows show a red ! badge with a tooltip; resolve conflicts before Review Plan
  • Empty/disabled tabs - Object Styles and Materials tabs remain visible but are disabled when empty; Parameters shows an empty/disabled message when scanning is unavailable or no mappable names are found.
  • Nested target dropdown parity - Types/Object Styles/Materials/Parameters follow the same global Sort mode + Threshold behavior as the parent Target dropdown, including colored similarity text and score suffixes in Similarity mode
  • Target dropdown wheel behavior - When a target dropdown list is open, mouse-wheel scrolling stays in that list (it does not scroll the background grid)
  • Parent target propagation - When the parent family Target changes while expanded, nested dropdowns repopulate automatically; rows you manually changed stay as-is
  • Consistent usage tab hydration - Expanded rows auto-refresh Object Styles/Materials once usage data is loaded, including rows restored from saved UI state
  • Deep-scan object-style augmentation rows - If you explicitly deep scan a family (typically only needed when it has zero instances), DS-discovered style refs can also appear in expanded Object Styles details (badged DS)
  • Deep-scan badge - Families use a single DS badge for deep-scanned rows; partial deep-scan warnings appear in the badge tooltip
  • Restored targets (DS) - If a saved mapping restores a target that is not currently in the dropdown options, GM injects it and marks it DS in the dropdown list item with a tooltip
  • Usage-linked Apply badge - OS, MAT, or OS+MAT indicates the family Apply state is linked from Object Styles/Materials tabs
  • Nested linkage badges - In expanded family row-details, Object Styles/Materials grids show LK badges (OS/MAT) on the exact nested rows currently driving linkage
  • Usage-link guardrail - OS/MAT linked Apply marks impact on the family row, but family-owned operations (type swaps, parameter maps, create-type) only run when that family row is explicitly user-owned
  • Instance cycler + zoom - Prev/next and zoom automatically navigate to the sampled instance even if it is in a different view

[Screenshot: Expanded family row]

Source: src/Tools/Common/GM/Shell/ViewModels/FamiliesPaneViewModel.cs:315
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.UsageAndFamilies.cs:385
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.CoreAndCommands.cs:1403
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.MappingInitAndInfrastructure.cs:323
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:110
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:1812
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:1615
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml.cs:23
Source: src/Tools/Common/GM/Features/Previews/ViewOpsService.cs:54
Source: src/DBTools.Themes/Behaviors/MouseWheelForwarder.cs:53
Source: src/Tools/Common/GM/Shell/Services/PlanBuildingService.cs:86
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.CoreAndCommands.cs:2191
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.MappingInitAndInfrastructure.cs:338
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.MappingInitAndInfrastructure.cs:817 Source: src/Tools/Common/GM/Shell/ViewModels/FamiliesPaneViewModel.cs:539 Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:1467 Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:1859 Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:2012 Source: src/Tools/Common/GM/Shell/ViewModels/FamiliesPaneViewModel.cs:781

Line Styles Tab

Map line styles to different line styles across your project.

[Screenshot: Line Styles tab]

Columns:

Column Description
Apply Check to include this mapping
Source The current line style
Target The replacement line style
Preview Visual preview of the style

Tips:

  • Line styles affect annotation elements, detail lines, and similar graphics
  • Preview swatches help you visually compare source and target

Object Styles Tab

Map Detail Items object styles (subcategory graphics) to different styles.

[Screenshot: Object Styles tab]

How it works:

Object styles in this tab are limited to Detail Items subcategories (non-line styles). Use this tab to:

  • Standardize graphics settings across Detail Items subcategories
  • Replace custom object styles with standard ones
  • Clean up unnecessary style variations

Additional features:

  • Families Using This Style - Select a style to see which families reference it
  • Preview pane - Shows the visual appearance of selected styles
  • Checking Apply auto-links the corresponding families in the Families tab
  • Unchecking Apply removes that style link; family Apply remains only if manually checked or linked by another source
  • Lock badges are informational (origin-only). To override a duplicate-seeded mapping, edit the target directly.
  • Commit opens each affected family document, ensures the mapped target style exists in that family (create if missing), syncs core style appearance from the host target, rewrites source-style references, then reloads the family into the project
  • Unsupported style mappings (outside Line Styles or Detail Items Object Styles scope) are ignored before commit and shown as warnings

Materials Tab

Replace materials throughout your project.

[Screenshot: Materials tab]

Columns:

Column Description
Apply Check to include this mapping
Source The material to replace
Target The replacement material
Color Preview Visual swatch showing the material color
Families Count Number of families using this material

Working with materials:

  1. Find the material you want to replace
  2. Select a target material from the dropdown
  3. The color preview helps you verify you're selecting the right material
  4. Check Apply and apply your changes
  5. Families affected by this material mapping are linked in Families tab (badge: MAT or OS+MAT)
  6. Commit updates both host-document material parameters and family-document material parameters in affected families; if target material is missing in a family doc, GM creates it and syncs core properties before rewriting references, then reloads the family
  7. In "Families Using This Material", the Apply indicator reflects active mapping linkage state (not just currently visible Families-tab rows), so linked families remain marked even when filtered out of the Families list
  8. Lock badges are informational (origin-only). To override a duplicate-seeded mapping, edit the target directly.
  9. Unsupported material mappings (source/target not resolvable in the host document) are ignored before commit and shown as warnings

Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.CoreAndCommands.cs:908
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:1615
Source: src/Tools/Common/GM/Features/Mapping/Writers/StyleChangeService.cs:203
Source: src/Tools/Common/GM/Features/Mapping/Writers/MaterialChangeServiceWriter.cs:209 Source: src/Tools/Common/GM/Shell/Services/PlanBuildingService.cs:231

Note: Material changes affect both appearance and any associated physical/thermal properties.

Shared Parameters Tab

Add shared parameters to families and categories, or map existing parameters to shared parameters.

[Screenshot: Shared Parameters tab]

Layout:

The tab has two panels:

  • Left panel - A category → family → type tree (curated categories) with instance sampling
  • Right panel - SP authoring cards for the selected type (Apply, Host-level vs Embed-in-family, Map From / Formula)

How to use it:

  1. Select an SP Group from the dropdown
  2. In the tree, expand a curated category (Doors, Mechanical Equipment, Walls, Windows)
    • Category labels include counts like Mechanical Equipment (12)
    • Empty categories show (0) and are dimmed
  3. Expand a family and select a type to see:
    • Existing parameters and sampled values
    • Shared parameters from the selected group that you can add / map
  4. Check Apply for each shared parameter you want to add
  5. Choose the binding mode:
    • Host-level - Parameter added to the category (project parameter)
    • Embed-in-family - Parameter added inside the family document
  6. Plan validation checks that each selected type is still aligned with its owning family/category context before commit; mismatched or stale selections are rejected with explicit errors before apply

Loading behavior:

  • On the first visit to the tab, GM lazily loads shared parameter groups and prewarms the curated categories (you may briefly see the loading overlay once).
  • After the initial load, expanding/collapsing nodes (including double-click) never triggers the progress overlay.

Instance Navigator:

When expanded, you can cycle through instances to see different parameter values:

  • Use the left/right arrows to navigate between instances
  • Click Zoom to Instance to jump to the instance even when it is not in the currently active view
  • The instance navigator appears centered between the SP Group dropdown and the SP Authoring pane when a type is selected and instances are sampled

Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.MappingInitAndInfrastructure.cs:755
Source: src/Tools/Common/GM/Shell/ViewModels/SharedParametersPaneViewModel.cs:246
Source: src/Tools/Common/GM/Shell/ViewModels/SharedParametersPaneViewModel.cs:1672
Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:3296
Source: src/Tools/Common/GM/Shell/Services/PlanBuildingService.cs:489

Step-by-Step Workflows

Workflow 1: Consolidating Duplicate Families

Goal: Find and merge duplicate families to reduce project bloat.

  1. Open Global Mapper
  2. Go to the Duplicates tab
  3. Wait for the automatic scan to complete (see the status bar)
  4. Review the Families group
  5. For each source row:
    • Select the keep target in Keep Target
    • Use the right details panel for candidate rationale when needed
    • Ensure Apply is checked
  6. Click Accept Applied
  7. Click Review Plan
  8. Review Commit Review
  9. Click Apply, then choose Accept + Continue (or Accept + Close GM). Use Rollback if you want to discard the apply session.

Tips:

  • Start with high-similarity matches (90%+) which are almost certainly duplicates
  • Lower the threshold to find more potential duplicates
  • Use Accept Applied to batch accept your staged rows

Workflow 2: Replacing a Family with a New Standard

Goal: Replace an old family with a new company-standard family throughout the project.

  1. Open Global Mapper
  2. Go to the Families tab
  3. Select the appropriate Category (e.g., Doors)
  4. Find your old family in the list
  5. Click the Target dropdown
  6. Select your new standard family
  7. Click + to expand and verify type mappings:
    • Map each old type to the corresponding new type
    • Use for types you don't want to transfer
  8. Check Apply on the family row
  9. Click Review Plan
  10. Review Commit Review and verify instance counts
  11. Click Apply, then choose Accept + Continue (or Accept + Close GM). Use Rollback if you want to discard the apply session.

Workflow 3: Adding Shared Parameters to Families

Goal: Add a shared parameter to multiple families at once.

  1. Open Global Mapper
  2. Go to the Shared Parameters tab
  3. In the left panel, select the parameter group containing your parameter
  4. In the right panel, select the Category (e.g., Mechanical Equipment)
  5. Expand the families you want to add the parameter to
  6. In the shared parameters section, check Apply for your parameter
  7. Choose the binding mode:
    • Host-level for a project parameter (easier, affects category)
    • Embed-in-family to add it directly to the family (requires family edit)
  8. Optionally, use Map From to copy values from an existing parameter
  9. Click Review Plan
  10. Review, click Apply, then choose Accept + Continue (or Accept + Close GM). Use Rollback if you want to discard the apply session.

Workflow 4: Standardizing Materials

Goal: Replace multiple similar materials with a single standard material.

  1. Open Global Mapper
  2. Go to the Materials tab
  3. Use the Search box to find materials by name
  4. For each material you want to replace:
    • Select the standard material in the Target dropdown
    • Check Apply
  5. Alternatively, use the Duplicates tab to find similar materials automatically
  6. Click Review Plan
  7. Review Commit Review to see affected elements
  8. Click Apply, then choose Accept + Continue (or Accept + Close GM). Use Rollback if you want to discard the apply session.

Settings and Options

Similarity Threshold

The threshold slider (0-100%) controls automatic target selection:

Threshold Effect
High (80-100%) Only very similar items are auto-selected; fewer suggestions
Medium (50-79%) Balanced - good matches suggested with some flexibility
Low (0-49%) More suggestions shown; useful for finding loose matches

Note: Manual selections are never changed by threshold adjustments. This applies to both top-level rows and expanded-row nested dropdowns. On the Duplicates tab, threshold controls which keep-target candidates appear for each source row. Opening a dropdown and closing it without choosing a different option does not count as a manual selection. Rows that were not manually changed continue to auto-select the highest-scoring target above threshold. If no option qualifies, GM keeps a blank programmatic default (no auto-assigned target); <Do Not Map> remains an explicit user choice in the expanded Types dropdown.

Source: src/Tools/Common/GM/Shell/ViewModels/FamiliesPaneViewModel.cs:1094
Source: src/Tools/Common/GM/Shell/ViewModels/FamiliesPaneViewModel.cs:1126

Sort Mode

Mode Description
Similarity Best matches shown first, with color-coded similarity scores
Alphabetical Items sorted A-Z; no similarity scoring displayed

Filters

Filter What It Does
Hide Unused Hide elements with zero instances in the project
Hide Unscanned Hide families that haven't been deep-scanned
Applied Only Show applied rows, including externally-originated and usage-linked family rows

Deep Scan

Some family information (like embedded parameters and nested families) requires a deep scan - a more thorough analysis that opens the family document. Deep scan is always user-initiated (GM does not auto-scan families when you expand a row).

When you need deep scan:

  • Unlocking expanded details for families with zero instances ("Scan required")
  • Getting embedded-definition details (for example nested family graphs) when they are not available from a placed instance

Note: For families with instances, expanded-row Object Styles and Materials are populated by walking a single placed instance, so deep scan is usually not necessary for styles/materials.

How to deep scan:

  1. Find a family row showing "Scan required" or missing details
  2. Click the Scan Family button in the expanded details
  3. Wait for the scan to complete (may take a few seconds)
  4. Details will populate once the scan finishes

Note: Deep scan results are cached globally, so you typically only need to scan each family once (unless the family changes). GM also attempts to hydrate deep-scan results from cache on startup for eligible families with 0 instances (strict restore; no banner on failure). Use Clear Deep Scan Cache to force a re-scan.

Important: Clicking Scan Family always performs a fresh deep scan and overwrites any existing cache entry.

Bulk scan shortcut (Families tab):

  • Use the top-bar Deep Scan Unscanned icon to scan all unscanned families with 0 instances in the current category (confirm dialog + progress overlay).

Cache restore note: If GM cannot restore cached deep-scan results in the current document (strict restore; for example missing/ambiguous styles or materials), it will log a warning and keep the family unscanned until you deep scan it.

Source: src/Tools/Common/GM/Shell/Services/DeepScanOrchestrationService.cs:128
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.MappingInitAndInfrastructure.cs:1144

Tips and Tricks

Power User Tips

  1. Use keyboard shortcuts

    • Ctrl+F - Focus the search box
    • Enter - Apply current selection
    • Escape - Cancel and close dialogs

  2. Work in batches

    • Check multiple rows, then apply all at once
    • Use Accept Applied in Duplicates for quick processing

  3. Preview before applying

    • Commit Review shows planned changes and post-apply outcomes
    • Use Close if something looks wrong (no model edits run until you click Apply)

  4. Save your progress

    • Mapping preferences are saved per-project
    • Reopen GM to see your previous selections

  5. Start with duplicates

    • Duplicate detection runs automatically and helps identify obvious consolidations
    • Accepted duplicates automatically lock related rows

Best Practices

  • Back up first - Even with Commit Review and Revit Undo, always save your project before bulk changes
  • Start small - Test with a few mappings before processing hundreds
  • Verify visually - After applying, spot-check some instances in views
  • Use filters - "Applied Only" filter helps review what you're about to change
  • Check quantities - The instance count shows how many elements will be affected

Troubleshooting

Common Issues

Problem Possible Cause Solution
No families appear Wrong category selected Select a different category from the dropdown
Target dropdown is empty No other families in category Load additional families into the project
"Scan required" message Family needs deep scan Click "Scan Family" to analyze the family
Review Plan button is disabled No mappings selected Check Apply/Map on at least one row
Changes didn't take effect Apply was canceled or rolled back Reopen Commit Review and click Apply again
Apply appears stuck near 90% A long-running Revit API call is still in progress Click Cancel once and wait for the in-flight call to return; if it does not recover, capture the latest DBTools log and report it
Cancel button seemed unresponsive An apply step is still finishing on the Revit call queue Keep the overlay open; cancellation is queued and cleanup runs as soon as the active Revit call returns
Some instances weren't replaced Type mapping incomplete Expand the family and verify all type mappings
"Locked by Families tab" Nested mapping set elsewhere Change the mapping in the Families tab instead

Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:286
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:548

Error Messages

Message What It Means What to Do
"Invalid mapping" Source and target are the same Select a different target
"Target not available" Target family/type was deleted Reload the family or choose a different target
"Deep scan failed" Family document couldn't be opened Check if the family file is accessible
"Conflict detected" Multiple sources map to the same target Resolve in the conflict panel

If Global Mapper Won't Open

  1. Ensure a Revit document is open and active
  2. Check that DBTools is properly loaded (look for the ribbon tab)
  3. Restart Revit and try again
  4. Check the Revit journal file for error details

Frequently Asked Questions

General Questions

Q: Can I undo changes made by Global Mapper?

A: Yes, in two ways:

  • Before applying, just Close Commit Review (no changes are made until you click Apply)
  • After applying (before accepting), Commit Review offers Rollback which rolls back the pending transaction group (discarding all apply changes from that session)
  • After accepting, you can use Revit's standard Undo command
  • GM applies operations through Revit transactions and wraps an accepted apply in a single undo group, so one accepted apply generally corresponds to one Undo entry.

Source: src/DBTools.Core/Revit/Transactions/CallGateTransactionGroupService.cs:1
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:1

Q: Will this affect linked files?

A: No, Global Mapper only modifies elements in the current document, not linked files.

Q: How long does applying changes take?

A: It depends on the number of elements being modified. A few dozen changes are nearly instant; thousands may take several minutes. A progress overlay shows the current status.

Q: What happens if I close Commit Review with the X button during commit?

A:

  • During apply: GM treats it like an explicit cancel request. It requests cancellation, runs cleanup, then closes the window.
  • After apply (pending accept/rollback): Commit Review prompts you to Accept + Continue, Accept + Close GM, or Rollback before closing.

Source: src/Tools/Common/GM/Shell/Views/CommitReviewWindow.xaml.cs:44
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:267

Q: Why can Commit Review show Failed: 1 while multiple families failed in Failed Operations?

A: Failed in the rules summary is the number of failed mapping rules. A single mapping rule can run across many families. Use the Families status line (Planned / Attempted / Failed) and the Failed Operations summary row (which aggregates per-family failures) to understand fan-out.

Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:770
Source: src/Tools/Common/GM/Shell/ViewModels/CommitReviewViewModel.cs:1013
Source: src/Tools/Common/GM/Features/Mapping/Writers/StyleChangeService.cs:489

Q: Are my mapping preferences saved?

A: Yes. Successful mappings and UI state are saved per-project and restored on reopen. On reopen, saved mapping targets are restored as suggestions, but Apply is left off by default so nothing is pre-enabled for commit. You can clear saved data from GM using:

  • Clear Saved Mappings (mapping selections)
  • Clear Saved UI State (tab/search/filter/scroll state)
  • Clear Deep Scan Cache (deep-scan data and DS badges)
  • Clear Saved Mappings writes an empty mapping snapshot immediately, so cleared mappings do not come back from stale saved files on reopen.
  • If GM cannot write saved mappings to disk, it logs the failure and shows an error banner (your mapping preferences may not persist for the next session).
  • Saved style mappings are restored only when source and target still exist in the same style scope (Line Styles or Object Styles). Stale cross-scope style mappings are ignored.
  • Style usage rows are normalized to canonical projection style IDs, so Object Styles family-usage counts stay tied to the real style after reopen/refresh.
  • Usage rows are constrained to the active tab universes (Materials, Line Styles, Detail Items Object Styles) so stale/out-of-scope IDs do not appear as extra rows.

Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.CoreAndCommands.cs:3118
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.CoreAndCommands.cs:3322 Source: src/Tools/Common/GM/Shell/Services/UiStatePersistenceService.cs:86 Source: src/Tools/Common/GM/Shell/ViewModels/UsagePaneViewModel.cs:676 Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.MappingInitAndInfrastructure.cs:487 Source: src/Tools/Common/GM/Shell/ViewModels/UsagePaneViewModel.cs:298 Source: src/Tools/Common/GM/Shell/Services/PlanBuildingService.cs:148

Families Questions

Q: What happens to parameters when I replace a family?

A: GM transfers parameter values only when you explicitly configure mappings in the expanded Parameters grid. Parameter mappings are name-based, scoped ((Instance) vs (Type)), and executed during type replacements.

If a type-scope mapping would write into a target type that already has instances, GM blocks commit until you choose a policy:

  • Keep target type values (skip type-scope copies)
  • Overwrite target type values (allow type-scope copies)

Source: src/Tools/Common/GM/Shell/ViewModels/FamiliesPaneViewModel.cs:781 Source: src/Tools/Common/GM/Features/Mapping/Writers/TypeChangeService.cs:451 Source: src/Tools/Common/GM/Shell/Services/MappingConflictService.cs:635

Q: Can I replace a family with one from a different category?

A: No, you can only replace families within the same category. This is a Revit limitation.

Q: What if the target family doesn't have all the types I need?

A: You can create new types directly in Global Mapper. In the expanded type mapping section, enable the row-level Create checkbox and enter a value in New Type Name.

Source: src/Tools/Common/GM/Shell/Views/GmShellWindow.xaml:1812
Source: src/Tools/Common/GM/Shell/ViewModels/ShellViewModel.CoreAndCommands.cs:1182

Materials Questions

Q: Will replacing a material change its appearance in renders?

A: Yes, the replacement material's appearance will be used everywhere the original material was applied.

Q: Can I preview materials before replacing?

A: Yes, the color preview swatch shows each material's appearance. Select a row to see more details in the preview pane.

Shared Parameters Questions

Q: What's the difference between Host-level and Embed-in-family?

A:

  • Host-level creates a project parameter bound to a category. Easier to set up, but the parameter lives in the project, not the family.
  • Embed-in-family adds the parameter directly to the family definition. Requires editing the family, but the parameter travels with the family to other projects.

Q: Can I map an existing parameter to a shared parameter?

A: Yes, use the "Map From" dropdown to select an existing parameter. Values will be copied from that parameter to the new shared parameter.

Keyboard Shortcuts

Shortcut Action
Ctrl+F Focus search box
Enter Confirm current action
Escape Cancel/close dialog
Tab Move between tabs
Space Toggle Apply checkbox (when row selected)

Getting Help

If you encounter issues not covered in this guide:

  1. Check the DBTools log files for detailed error information
  2. Contact your BIM Manager or IT support
  3. Visit the DBTools support resources

Summary

Global Mapper streamlines bulk element management in Revit by providing:

  • Intelligent matching - Similarity scoring suggests the best replacements
  • Comprehensive coverage - Families, types, materials, styles, and parameters
  • Safe workflow - Review outcomes before finalizing, with full rollback support
  • Time savings - Replace hundreds of elements in minutes instead of hours

Start with the Duplicates tab to find quick wins, then use the Families tab for targeted replacements. Remember to review Commit Review before committing.

Edit this page