Chapter 1: Getting Started
What Bridger does, how it's organized, and what you're looking at.
The Problem Bridger Solves
Data migrations are deceptively complex. A medium-sized conversion might involve dozens of source tables, hundreds of target columns, and thousands of individual mapping decisions. Each decision carries context: where the data comes from, how it transforms, who approved it, and what happens when the source value doesn't fit the target.
Teams typically manage this in spreadsheets. That works for a while. Then the target schema changes and half the mappings need revisiting. A second analyst joins and starts a parallel copy. The client reviews a printed report and marks it up, but nobody can reconcile the handwritten notes with the master file. The developer building the ETL scripts has version 3; the business analyst has version 5.
Bridger replaces the spreadsheet with a purpose-built environment for planning and documenting data migrations. It tracks every mapping decision with status, transformation logic, and structured notations. It enforces consistency through shared configuration. It generates reports for stakeholders and validation scripts for developers. And it keeps everything in a single portable file that the whole team works from.
Bridger is a planning tool. It documents what should happen during a migration and tracks progress toward completion. The actual data movement happens in your ETL tools and conversion scripts. Bridger ensures everyone agrees on the plan before code gets written.
How Bridger Organizes a Migration
Bridger uses a layered structure to separate reusable definitions from project-specific work. Understanding these layers is the key to working efficiently.
Workbook
Everything lives in a single workbook file with a .bridger extension. The workbook contains your Configuration, your Library, and one or more Projects. It is self-contained—no database connections, no network dependencies. You can email it, check it into version control, or drop it on a USB drive. The file format is JSON, so it's human-readable in a pinch, but you'll rarely need to look at it outside of Bridger.
Configuration
Configuration defines the vocabulary and rules that all projects in the workbook share. This includes status codes that track mapping progress, notation types for structured documentation, logic templates for common transformation patterns, exception codes for error handling, common functions for reusable validation routines, auto-mapping rules for automated column matching, special source tables for non-column mapping targets, and report templates for stakeholder output.
Bridger ships with a set of defaults for all of these. You can start mapping immediately and adjust the configuration as your team's workflow takes shape. Every configuration element is fully customizable.
Library
The Library stores table and column definitions independently of any project. It has two sides: a Source Library for legacy system schemas and a Target Library for destination system schemas. Import your data dictionaries here once, then pull tables into projects as needed. When a schema changes, update the Library and sync the changes down to any projects that use those tables.
The Library is optional. You can import tables directly into a project without going through the Library first. But for any migration that spans multiple projects or expects schema evolution, the Library saves significant rework.
Project
A Project is where the actual mapping work happens. Each project has its own set of source tables, target tables, and the mappings between them. A workbook can hold multiple projects—one per functional area, one per migration phase, or however your team organizes the work. Projects are independent of each other but share the workbook's Configuration and can pull tables from the same Library.
Mapping
A Mapping is the documented relationship between a source endpoint and a target endpoint. The source endpoint is typically a column from a source table, but it can also be a Source Group (multiple columns contributing to one target) or a special source table (for exclusions, defaults, and stored values). The target endpoint is a single target column.
Each mapping carries a status, transformation logic, and zero or more notations. The status tracks where the mapping is in your review workflow. The transformation logic describes how the source data becomes the target data. Notations provide additional context—business rules, edge cases, historical decisions, test cases.
The Workspace
When you open a workbook and select a project tab, the workspace is divided into several areas.
Source Panel
The left side of the workspace shows your source tables and their columns in a tree view. Tables are listed in the order you've arranged them (you can reorder by dragging). Expand a table to see its columns. This is where you drag from when creating mappings.
Target Panel
The right side mirrors the source panel but shows your target tables and columns. This is where you drop when creating mappings. The same expand/collapse and reordering controls apply.
Mappings Panel
The center area shows all mappings in the current project, grouped by table. Each row shows the source column, a connector, the target column, and the current status. Selecting a mapping displays its details in the properties pane. The mappings panel supports a view toggle that switches between Source → Target grouping (organized by source table) and Target ← Source grouping (organized by target table), letting you work from whichever perspective fits your current task.
Properties Pane
Below or beside the main panels (depending on your layout), the properties pane shows detailed information about whatever is currently selected—a table, a column, or a mapping. For mappings, this includes the full status, all attached notations organized by type in a tabbed interface, and indicator values. For tables and columns, it shows schema information, indicators, and any table-level or column-level notations.
The Tab Bar
Along the top of the workspace, a tab bar provides access to everything in the workbook.
Project Tabs
Each project appears as a named tab. Click a tab to switch to that project's workspace. Right-click a tab to access project operations: Rename, Duplicate, Properties (name, description, and project-level settings), or Delete.
The [+] Tab
The last tab in the bar is always a [+] button. Click it to create a new project. Bridger assigns a default name that you'll want to change immediately—"New Project" isn't going to help anyone six months from now.
Library Tab
The Library tab switches to the Library workspace, which has its own source and target panels for managing your reusable table definitions. The Library workspace looks similar to the project workspace but focuses on schema management rather than mapping.
Configuration Tab
The Configuration tab opens a panel with editors for all the shared configuration elements: status codes, notation types, indicators, logic templates, exception codes, common functions, auto-mapping rules, special tables, and report templates. Changes here affect all projects in the workbook.
The Menu Bar
The menu bar provides access to file operations, tools, and help.
File Menu
| Item | What It Does |
|---|---|
| New Workbook | Creates a new workbook with default configuration. Prompts to save the current workbook if it has unsaved changes. |
| Open | Opens an existing .bridger file. |
| Save / Save As | Saves the current workbook. Save As lets you write to a new filename. |
| Recent Files | Quick access to recently opened workbooks. |
| Import from Excel | Reconstructs a Bridger project from a mapping spreadsheet using a report template to interpret the structure. Covered in Chapter 8. |
| Export to… | Generates an Excel report from the current project using a selected report template. Covered in Chapter 6. |
Tools Menu
| Item | What It Does |
|---|---|
| Settings | Opens the Settings dialog for theme selection, quality indicators toggle, and AI features toggle. |
| AI Configuration | Configures the connection to a local Ollama instance for AI-assisted mapping. Only visible when AI features are enabled in Settings. Covered in Chapter 11. |
| Generate Validation SQL | Produces validation query skeletons from your mapping data. Covered in Chapter 10. |
Dashboard Menu
Provides quick access to report generation without navigating through File → Export. Select a report template and Bridger opens a preview of the current project's data in that format.
Help Menu
Opens this user guide and displays the Welcome tip dialog, which provides a brief orientation for first-time users.
View Controls
Source ↔ Target Toggle
The mappings panel can display your work from two perspectives. The default Source → Target view groups mappings by source table—useful when you're working through the legacy system asking "where does this data go?" Click the toggle to switch to Target ← Source view, which groups by target table—useful when you're reviewing the destination schema asking "where does this data come from?" The toggle is a button in the mappings panel toolbar.
Zoom
The entire interface scales smoothly. Use Ctrl++ to zoom in, Ctrl+- to zoom out, and Ctrl+0 to reset to the default size. This is a global setting—it affects all panels, trees, and text.
Theme
Bridger supports light and dark themes. Switch between them in the Settings dialog under the Tools menu. Dark mode adjusts all UI elements for reduced eye strain during extended work sessions. Theme changes take effect after restarting the application.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Ctrl+N | New workbook |
| Ctrl+O | Open workbook |
| Ctrl+S | Save workbook |
| Ctrl++ | Zoom in |
| Ctrl+- | Zoom out |
| Ctrl+0 | Reset zoom |
| Ctrl+Click | Toggle selection of individual items |
| Shift+Click | Select a range of items |
| Double-click | Edit mapping or jump to associated columns |
File Basics
The .bridger File
A workbook is stored as a single .bridger file. The format is JSON, which means it's plain text, version-control friendly, and recoverable in an emergency with any text editor. In normal use you'll never interact with the JSON directly.
Window Title
The window title bar shows three pieces of information: the active project name, the workbook filename, and a dirty indicator (an asterisk) when there are unsaved changes. This gives you constant awareness of which file you're working in and whether you need to save.
File Association
Bridger registers the .bridger file extension during installation. Double-clicking a .bridger file in Windows Explorer opens it directly in Bridger. You can also pass a filename as a command-line argument.
Auto-Recovery
If Bridger encounters an issue during startup or detects potential problems with a workbook on load, it runs an automatic repair pass. The results of any repairs are displayed in a summary dialog so you know exactly what was adjusted. This includes things like orphaned column references, missing indicator definitions, and database field inconsistencies.
Welcome Tip
On first launch, Bridger displays a Welcome tip dialog with a brief orientation. You can revisit this at any time from the Help menu. The built-in user guide (the document you're reading now) is also accessible from the Help menu.
What's Next
You now have the lay of the land—what Bridger is for, how it organizes migration work, and what the workspace looks like. In Chapter 2: Building Your First Map, you'll import tables, create your first mapping, and work through the basic workflow from start to finish.