Skip to content

Import

Jump to bottom
Herculino Trotta edited this page Jan 25, 2026 · 11 revisions

WYGIWYH has a CSV Import function, currently in beta.

Adding a Profile

Profiles are where you store the configuration for a given import. For example, if you have 3 banks with 3 different CSV formats, you will create 3 different profiles, one for each bank.

A profile is composed of 3 fields:

  • name: An unique name
  • yaml_config: YAML configuration following the schema specification
  • version: Schema version number (currently only Version 1 is available)

You can access the profiles page by navigating to Management > Import on the navbar.

From there you can click the + button to either add a new profile from scratch or use one of the available presets created by the community.

Importing

After adding a Import Profile, each profile will have a Import button, you can click it to upload a file.

Seeing Import status

All Import Profiles have a Runs button, click there to seem information about the file you imported.

The YAML Schema

Version 1

Each YAML schema is composed of 3 nodes

settings (required)

file_type: Currently only supports "csv"

CSV Specific settings

name type default definition
skip_errors bool false Whether to continue on row errors or halt execution
delimiter str "," CSV delimiter character
encoding str "utf-8" File encoding
skip_lines int 0 Number of surplus CSV lines to skip above the column headers. Do not use this to skip the column header row, it is needed for the import to work
trigger_transaction_rules bool true Whether to trigger created transaction rules when importing a new transaction
importing str *required Type of data being imported (transactions, accounts, currencies, etc.)

Example

settings:
  file_type: csv
  delimiter: ","
  encoding: utf-8
  skip_lines: 1
  importing: transactions
  trigger_transaction_rules: true
  skip_errors: false

mapping (required)

This is where you configure what columns should be imported as what.

The common fields are:

name type default definition
target str *required Field to map to
source Optional[str] or Optional[list] None The name of the CSV column you want to map to. If empty or not defined, the field will be generated from default, transformations or ignored.
default Optional[str] None The default value if none present
required bool false If this value should be present. Will halt execution or skip row depending on "skip_errors" setting.

transformations

Transformations allow you to transform a value before it is coerced.

replace
name type default definition
type str *required Either "regex" or "replace"
pattern str *required Pattern to match
replacement str *required Value to replace with
exclusive bool false If it should match against the result of the last transformation or the original value
date_format
name type default definition
type str *required "date_format"
original_format str *required The format your date is in
new_format str *required The format to reformat your date to
merge
name type default definition
type str *required "merge"
fields list[str] *required the CSV columns to merge
separator str " " What to separate your merged values with
split
name type default definition
type str *required "split"
separator str "," Separator to use when splitting
index Optional[int] 0 0-based index to return as value. None to return all.
hash
name type default definition
type str *required "hash"
fields list *required CSV Columns to hash together

Accepted targets

importing: transactions

  • account
  • type
  • is_paid
  • date
  • reference_date
  • amount
  • description
  • notes
  • tags
  • entities
  • category
  • internal_note
  • internal_id

importing: category

  • category_name
  • category_mute
  • category_active

importing: tags

  • tag_name
  • tag_active

importing: entities

  • entity_name
  • entity_active

importing: accounts

  • account_name
  • account_group
  • account_currency
  • account_exchange_currency
  • account_is_asset
  • account_is_archived

importing: currency

  • currency_code
  • currency_name
  • currency_decimal_places
  • currency_prefix
  • currency_suffix
  • currency_exchange

Target-specific fields

Some targets have specific fields:

type

For targets account, category, tags, entities and account_group you can set type to either id or name. This will define what to filter for when creating new objects.

For targets account_currency, account_exchange_currency and currency_exchange, you can set type to either id, name or code. This will define what to filter for when creating new objects.

create

For targets tags, entities, category, and account_group you can set create to true or false. Defaulting to true. This will create new objects if they don't exist. This can only be used with type name.

format

For targets date and reference_date, you must set the format config with a valid Datetime format. This can also be a list of formats, each one will be tried a match is found.

detection_method

For target type you can set detection_method to sign for detecting transaction type from a amount sign (negative is Expense and positive is Income); always_income or always_expense.

For target is_paid you can set detection_method to boolean to detect basic boolean strings; always_paid or always_unpaid.

Example

mapping:
  date:
    target: date
    source: transaction_date
    format: "%Y-%m-%d"

  reference_date:
    target: reference_date
    source: transaction_date
    format: 
      - "%Y-%m-%d"
      - "%d-%m-%Y"
      - "%m-%d-%Y"
  
  amount:
    target: amount
    source: value
    required: true
    transformations:
      - type: replace
        pattern: "$"
        replacement: ""

deduplication optional

Currently there's only one deduplication rule type:

compare

A compare deduplication rule compares the mapped row to a existing transactions.

compare can have a match_type of lax, for case-insensitive comparison or strict for case-sensitiveness.

Lastly, use fields to name what to compare against (use the target naming).

Example

deduplication:
  - type: compare
    fields:
      - date
      - amount
      - account
      - entities
    match_type: strict

Note

This is optional, omit it from your config file to disable deduplication.

.qif files import

.qif files or Quicken Interchange Format, are a deprecated format for exporting finance data. QIF files are supported as a file_type.

Since they have a strict format, you don't need to do any mapping, just pay attention to:

  • The date_format setting as it can vary between files. Check what your files use
  • The account name is inferred from the file name, so make sure to rename your files accordingly

A preset is available with the basic settings you need to import these files.

New versions

New schema versions will be created when a new addition or bug fix can't keep backwards compatibility. This is not valid for the time Version 1 remains in beta.

Note

Severe bugs may be fixed by breaking backwards compatibility.

Clone this wiki locally