Import

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 header lines to skip
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_lines" 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, tags, entities 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 (required)

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:
      - internal_id
      - name
    match_type: strict

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.