From 3ecd562b04d31bd68060e174e39e5f977cb235b1 Mon Sep 17 00:00:00 2001 From: Herculino Trotta Date: Thu, 23 Jan 2025 22:28:00 -0300 Subject: [PATCH] Updated Import (markdown) --- Import.md | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 178 insertions(+), 1 deletion(-) diff --git a/Import.md b/Import.md index d1ae054..f0d48b7 100644 --- a/Import.md +++ b/Import.md @@ -20,4 +20,181 @@ After adding a Import Profile, each profile will have a `Import` button, you can # Seeing Import status -All Import Profiles have a `Runs` button, click there to seem information about the file you imported. \ No newline at end of file +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 + +```yaml +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] | 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 | 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 + +##### `type` + +For targets `account`, `category`, `account_group` you can set type to either "id" or "name". This will hel + + + +Some targets have specific fields + +#### Example + +```yaml +mapping: + date: + target: date + source: transaction_date + required: true + format: "%Y-%m-%d" + + amount: + target: amount + source: value + required: true + transformations: + - type: replace + pattern: "$" + replacement: "" +``` + + +## 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.