The Tiller Labs Migration Helper is built to help users migrate enriched personal-finance data— e.g. categories, splits, manual balances— from an old “source” spreadsheet to a new “destination” spreadsheet.
The Migration Helper is a quick-and-dirty best-effort by Tiller Labs at a very complex migration problem. We hope this tool helps you, but please be aware that this workflow will not work for everyone.
Migration Helper Functions
The Migration helper is designed to migrate enriched account data including:
- Categories applied to transactions
- Notes applied to transactions
- Transactions that have been split
- Transactions that have been manually entered
- “Unlinked” accounts & balances that have been manually added
Migration Helper Compatibility
Several sheets and columns are required for the migrator to run. A compatibility check will run before the Migration Helper makes any changes.
Transaction ID column is required in both the source and destination spreadsheets to migrate Categories and Notes.
Transaction ID uniquely identifies transactions in the Tiller database. This field is used by the Migration Helper to identify matches across the two spreadsheets.
The Migration Helper is designed to migrate a limited number of standard Tiller columns and fields (above). The tool may not work well in spreadsheets with extensive modifications & special columns.
Recent Changes to Tiller Spreadsheet Architecture
Tiller spreadsheets have improved since summer 2019. If you have an older sheet
- Version metadata for Tiller Labs compatibility & sheet management
- Uniquely identifying accounts using
Account IDinstead of
Configuration + How The Migration Helper Works
The Migration Helper can move data from the source to destination spreadsheet for each of the following sheets:
- Balance History
Using the checkbox controls in the sidebar, the user can choose which sheets to include in the migration process. All sheets are included by default.
Identify the source spreadsheet by opening it in a separate tab then pasting its URL (or Spreadsheet ID) into the text box in the sidebar.
Categories and Notes
When the Migration Helper finds a matching
Transaction ID between the source and the destination spreadsheets, it will move the assigned category and note from the source to the destination.
For both Categories and Notes, a dropdown allows the user to choose to overwrite categories/notes either “Always” or “When Blank”. If “Overwrite Always” is selected, categories/notes will be overwritten with source data in the destination sheet whenever a match is found. If “Overwrite When Blank” is selected, categories and notes will be overwritten with source data in the destination sheet when a match is found AND the category/note field in the destination is blank.
When the migration helper finds the same
Transaction ID applied to several transactions in the source, those rows are flagged as a split transaction. If the destination sheet contains a matching
Transaction ID, the Migration Helper will remove the row in the destination sheet and add all rows with the
Transaction ID to the destination spreadsheet. In this way, splits are replicated into the destination spreadsheet.
Manually-added transactions in the source spreadsheet (i.e. rows with no
Transactions ID) will be moved to the destination spreadsheet if the “Manually Created” dropdown is set to “Migrate All”. (If the dropdown is set to “Ignore”, transactions with no
Transaction ID will be discarded in the migration.)
The Migration Helper will move any categories that do not exist in destination from the source spreadsheet.
Budget migration (from the Categories) sheet is not implemented at this time. Budgets must be migrated manually.
A dropdown offers two different approaches to category migration…
Merge with Source
For any categories that exist in both the source and destination spreadsheets, the Migration Helper will overwrite
Hide From Reports configuration to match the source spreadsheet.
Categories that exist only in the destination will be preserved.
Overwrite with Source
The destination categories will be wiped away before source categories are migrated to the destination sheet, providing a fresh start. This approach is preferred when migrating into a spreadsheet with default categories as unused destination categories are removed rather than orphaned.
If a Balance History entry has
9999 assigned in the legacy
Index column, the Migration helper will assign all balance entries with a matching
Account name a new
Account ID. Having a valid
Account ID is required for many Tiller Labs templates. (The
Index column is not supported in Tiller Labs templates.) Balance entries that previously had index
9999 and are assigned an
Account ID will be migrated to the destination spreadsheet.
Balance History entries with
Account ID prefix
manual: (i.e. current manual balance entries) will be moved to the destination spreadsheet.
How To Use The Migration Helper
This workflow works best when the destination spreadsheet is a recently-created/new Tiller spreadsheet with linked accounts and an initial feeds update.
The following steps are recommended:
- Create a new Tiller spreadsheet using either the Foundation Template in the Tiller Console or a new Google Sheet
- Link accounts to the new spreadsheet using the Tiller Feeds add-on
- Run an initial feeds update on the new spreadsheet using the Tiller Feeds add-on
- Open the Tiller Labs add-on in the new spreadsheet
- Navigate to the Labs Tools option in the Tiller Labs add-on main menu
- Choose the Migration Helper in the Labs Tools submenu
- Copy the URL from your source spreadsheet— not the open destination spreadsheet— and paste it into the textbox below
- Set your migration configuration options per the instructions above
- Click Migrate
Once the process completes, carefully review your data to ensure you are satisfied.