Skip to content

CATEGORY_IMPORT_EXPORT_GUIDE.md

Latest commit

 

History

History
396 lines (315 loc) · 11.8 KB

CATEGORY_IMPORT_EXPORT_GUIDE.md

File metadata and controls

396 lines (315 loc) · 11.8 KB

Category Import/Export Guide

Overview

The Transaction Manager now supports importing and exporting categories as JSON files. This allows you to:

  • Backup your category rules
  • Share categories with other users
  • Migrate categories between databases
  • Version control your category configurations

How to Use

Exporting Categories

  1. Go to the 🏷️ Manage Categories tab
  2. Click the 📤 Export Categories button
  3. Select which categories to export using the checkboxes
    • Use Select All to choose all categories
    • Use Deselect All to clear all selections
    • Manually check/uncheck individual categories as needed
  4. Click Export Selected
  5. Choose a location and filename for the export file (default: categories_export_YYYYMMDD.json)
  6. Click Save

✓ Only your selected categories will be exported to a JSON file with metadata

Importing Categories

  1. Go to the 🏷️ Manage Categories tab
  2. Click the 📥 Import Categories button
  3. Select a JSON file containing exported categories
  4. Select which categories to import using the checkboxes
    • Use Select All to choose all categories from the file
    • Use Deselect All to clear all selections
    • Manually check/uncheck individual categories as needed
    • Each category shows its pattern type and pattern for reference
  5. Choose import options:
    • ☐ Update existing categories - If checked, categories with the same name will be updated with new patterns
    • If unchecked, duplicate category names will be skipped
  6. Click Import Selected
  7. After import, you'll be prompted to Recategorize All Transactions to apply the new rules

Export File Format

The exported JSON file contains:

{
  "version": "1.0",
  "exported_at": "2025-10-15T12:00:00.000000",
  "category_count": 5,
  "categories": [
    {
      "name": "Amazon",
      "pattern": "AMAZON",
      "pattern_type": "contains",
      "description": "Amazon purchases",
      "color": "#FF9900"
    },
    ...
  ]
}

Field Descriptions

  • version: Export format version (for compatibility)
  • exported_at: Timestamp when the export was created
  • category_count: Number of categories in the file
  • categories: Array of category objects

Category Object Fields

Field Required Description Example
name ✓ Category name (must be unique) "Amazon"
pattern ✓ Pattern to match in transaction descriptions "AMAZON MKTPL"
pattern_type ✓ Type of pattern matching "contains", "regex", "startswith", "endswith", "exact"
description Optional description "Amazon marketplace purchases"
color Optional hex color code "#FF9900"

Pattern Types

contains (most common)

Matches if the pattern appears anywhere in the transaction description (case-insensitive).

Example:

{
  "name": "Amazon",
  "pattern": "AMAZON",
  "pattern_type": "contains"
}

Matches: "AMAZON MKTPL", "Amazon.com", "Purchase from Amazon"

regex (powerful)

Uses regular expressions for complex matching.

Example:

{
  "name": "Gas Stations",
  "pattern": "SHELL|CHEVRON|ARCO|76",
  "pattern_type": "regex"
}

Matches: "SHELL GAS", "CHEVRON STATION", "ARCO #123", "76 STATION"

startswith

Matches if the description starts with the pattern.

Example:

{
  "name": "Apple Services",
  "pattern": "APPLE.COM",
  "pattern_type": "startswith"
}

Matches: "APPLE.COM/BILL", "APPLE.COM iTunes"

endswith

Matches if the description ends with the pattern.

exact

Matches only if the description exactly equals the pattern (case-insensitive).

Cherry-Picking Categories

Both import and export support cherry-picking - selecting only specific categories you want to work with.

When to Use Cherry-Picking

Export Specific Categories:

  • Share only relevant categories with someone (e.g., only business categories, not personal ones)
  • Create focused category sets for specific purposes
  • Export only tested/finalized categories, excluding experimental ones
  • Backup specific category groups separately

Import Specific Categories:

  • Import only categories you need from a larger set
  • Avoid importing categories that conflict with your current setup
  • Test new categories one at a time
  • Selectively merge category sets from different sources

How Cherry-Picking Works

  1. Export Dialog:

    • Shows all your current categories with checkboxes
    • All categories are selected by default
    • Deselect categories you don't want to export
    • Only checked categories are saved to the JSON file

  2. Import Dialog:

    • Shows all categories found in the import file with checkboxes
    • All categories are selected by default
    • Deselect categories you don't want to import
    • Only checked categories are processed

Examples

Example 1: Share Business Categories Only

1. Click Export Categories
2. Click "Deselect All"
3. Manually check only business-related categories:
   ☑ Office Supplies
   ☑ Business Travel
   ☑ Client Meals
   ☐ Personal Shopping (leave unchecked)
   ☐ Family Dining (leave unchecked)
4. Export → share with business partner

Example 2: Test New Categories Individually

1. Receive a categories file with 20 new categories
2. Click Import Categories
3. Click "Deselect All"
4. Check only 1 category to test:
   ☑ Streaming Services
5. Import → Recategorize All → Review results
6. If good, repeat for other categories

Example 3: Merge Without Duplicates

1. Import a categories file
2. Review the list - some already exist
3. Uncheck categories you already have:
   ☐ Amazon (already have this)
   ☐ Groceries (already have this)
   ☑ Gas Stations (new - keep checked)
   ☑ Utilities (new - keep checked)
4. Import Selected

Use Cases

1. Backup Categories Before Making Changes

Before making major changes to your category rules:

  1. Export your current categories
  2. Save the file with a descriptive name (e.g., categories_backup_before_cleanup.json)
  3. Make your changes
  4. If needed, you can re-import the backup

2. Default Categories

The application comes with a set of default categories loaded from default_categories.json:

  • Amazon categories (Digital, Marketplace, POS)
  • Apple services and subscriptions
  • Streaming services (Netflix, Peacock, Prime Video)
  • Gas stations and transportation
  • Food delivery (DoorDash, etc.)
  • Banking (Capital One, Cash App)
  • Entertainment (Audible, Kindle)

These defaults are automatically loaded when the database is first initialized. You can:

  • Customize the default_categories.json file to match your preferences
  • Export your current categories to see the format
  • Import different default sets as needed

3. Share Categories with Team/Family

If multiple people use the Transaction Manager:

  1. One person creates and refines category rules
  2. Export the categories
  3. Share the JSON file with others
  4. Others import the categories to get the same rules

4. Create Category Templates

Build category sets for different purposes:

  • categories_personal.json - Personal expense categories
  • categories_business.json - Business expense categories
  • categories_tax.json - Tax-related categories

Switch between them by importing as needed.

5. Version Control

Store your category files in Git or another version control system to:

  • Track changes over time
  • Revert to previous versions
  • Document why categories changed

Import Behavior

New Categories

Categories that don't exist in your database will be added.

Duplicate Categories (same name)

Two options:

Option 1: Skip duplicates (default)

  • Existing categories remain unchanged
  • Only new categories are added
  • Duplicate names are reported as warnings

Option 2: Update existing (checkbox enabled)

  • Categories with matching names are updated with new patterns
  • Useful when importing refined versions of categories

After Import

After importing categories, you should:

  1. Click Recategorize All to apply the new rules to existing transactions
  2. Review the 📊 Summary tab to see the updated categorization

Tips & Best Practices

1. Use Descriptive Names

✓ "Amazon Marketplace"
✗ "AMZ"

2. Add Descriptions

Help yourself remember what each category is for:

{
  "name": "Subscription Services",
  "pattern": "NETFLIX|SPOTIFY|HULU",
  "pattern_type": "regex",
  "description": "Monthly streaming and entertainment subscriptions"
}

3. Test Patterns Before Exporting

  1. Create a category in the GUI
  2. Click Recategorize All to test it
  3. View results in the Summary tab
  4. Once satisfied, export

4. Use Colors Consistently

Assign meaningful colors:

  • 🔴 Red (#F44336) - Mandatory expenses (utilities, rent)
  • 🟢 Green (#4CAF50) - Income, refunds
  • 🔵 Blue (#2196F3) - Discretionary spending
  • 🟡 Yellow (#FFC107) - Variable expenses (groceries, gas)

5. Regular Exports

Export your categories regularly (monthly/quarterly) as backups.

Troubleshooting

"Invalid JSON file" Error

  • Ensure the file is valid JSON (use a JSON validator)
  • Check for missing commas, brackets, or quotes
  • Don't edit the file manually unless you're familiar with JSON

"Category already exists" Warnings

  • This is normal if importing to a database that already has some categories
  • Enable "Update existing categories" if you want to replace them
  • Or manually delete conflicting categories before importing

Categories Not Matching After Import

  • Click Recategorize All in the Manage Categories tab
  • This applies all category rules to existing transactions

Import Shows 0 Categories

  • Check that the JSON file has the correct format
  • Ensure it has a "categories" array
  • See the sample file: categories_sample.json

Example Workflows

Weekly Cleanup Workflow

1. Review uncategorized transactions in Summary tab
2. Create new categories for common patterns
3. Click Recategorize All
4. Export categories → categories_backup_YYYY-MM-DD.json

Migration to New Computer

1. On old computer: Export Categories
2. Copy JSON file to new computer
3. On new computer: Install Transaction Manager
4. Import the categories JSON file
5. Import your transaction database or CSV files
6. Click Recategorize All

Sharing with Family Member

1. Export your refined categories
2. Email/share the JSON file
3. Family member imports the file
4. Both now use consistent categorization rules

File Format Compatibility

Current Version: 1.0

The current export format is version 1.0. Future versions will remain backward compatible.

Legacy Format Support

The importer also supports the legacy format (just an array of categories without metadata):

[
  {
    "name": "Amazon",
    "pattern": "AMAZON",
    "pattern_type": "contains"
  }
]

Related Features

  • CSV Import Settings: See IMPORT_SETTINGS_GUIDE.md
  • Category Management: Use the Manage Categories tab for creating/editing categories
  • Recategorize All: Applies all category rules to existing transactions

Summary

✓ Export - Backup and share your category rules ✓ Import - Restore or load category sets ✓ Cherry-Pick - Select specific categories to export or import ✓ JSON Format - Human-readable and version-control friendly ✓ Flexible - Skip or update duplicates as needed ✓ Safe - Preview before importing, backup before changes

Key Features

  • Select All / Deselect All buttons for quick selection
  • Checkbox selection for both import and export
  • Pattern preview showing what each category matches
  • Validation ensures at least one category is selected
  • Counts show exactly how many categories are being processed

For more help, see the main README.md or the application's help documentation.