How To Use The Migration Helper From Tiller Labs


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
  • Categories
  • “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.

The 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 ID instead of Index

Configuration + How The Migration Helper Works

The Migration Helper can move data from the source to destination spreadsheet for each of the following sheets:

  • Transactions
  • Balance History
  • Categories

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.

Source Spreadsheet

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.

Split Transactions

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

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 Group, Type and 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.

Balance History

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 Source Spreadsheet
  • Set your migration configuration options per the instructions above
  • Click Migrate

Once the process completes, carefully review your data to ensure you are satisfied.