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.

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.

Adding a Profile

Importing

Seeing Import status

The YAML Schema

Version 1

settings (required)

CSV Specific settings

Example

mapping (required)

transformations

replace

date_format

merge

split

hash

Accepted targets

Target-specific fields

type

create

format

detection_method

Example

deduplication optional

compare

Example

New versions

`type`

`create`

`format`

`detection_method`

deduplication `optional`