Abrest Import — Configuration Reference

Each import job is driven by a YAML configuration stored in S_BLOCKYAML.BLOCK_CONTENT. The importer locates the header row (the first row containing every external column name referenced in fields) and then processes each subsequent row in this order: hierarchy detection → column mapping → value/type fields → group path resolution → item resolution → tag assignment → optional translation → DB insert.

Complete example

Pricelist in XLSX with a three-level hierarchy detected from cell styling, supplier-category overrides, tag assignment, and Ukrainian → English translation.

---
file_type: xlsx
sheet: 0

global:
    root_group_id: 0
    tovar_type: 1
    translation:
        from: uk
        to: en
        translate_items: true
        translate_groups: true
        translate_tags: true

fields:
    GROUP_ID:
        resolve: group_path
        levels:
            - name: category
              tag: CATEGORY
              detect:
                  column: 0
                  method: formatting
                  bold: true
                  font_size: 14
            - name: subcategory
              detect:
                  column: 0
                  method: formatting
                  bg_color: 92D050
                  bold: true
            - name: product_type
              detect:
                  column: 0
                  method: formatting
                  bg_color: D9FECC
        categories:
            depth: 2
            default: tag
            default_tag_name: ProductType
            mapping:
                - source: "House brand"
                  action: map
                  group_id: 42
                - source: "Legacy products"
                  action: exclude
                - source: "Mixed fertilisers"
                  action: inherit
    TOVAR_ID:
        resolve: find_or_create
        name_source: "Назва товару"
        ean_source: "Штрихкод"
        article_source: "Артикул"
    PRICE:
        source: "Ціна"
        type: number
    IMPORT_DATE:
        value: today
        tag: IMPORT_DATE
...

Top-level keys

Key	Required	Purpose
`file_type`	yes	`csv`, `xlsx`, `xls`, `xml`
`sheet`	no	Sheet index for XLSX/XLS (default `0`)
`global`	no	Document-level defaults (root group, item type, translation)
`fields`	yes	Field definitions — one entry per DB field or resolved value

`global`

Optional section for document-level settings that apply to the entire import.

Key	Default	Description
`root_group_id`	`0`	Parent group ID used as the starting point for `resolve: group_path`
`tovar_type`	`1`	Item type written to `R_TOVAR.TTYPE` when a new item is created (`1` = goods, `2` = service/work)
`translation`	—	LLM translation settings (see below)

`global.translation`

global:
    translation:
        from: uk
        to: en
        translate_items: true
        translate_groups: true
        translate_tags: true

Key	Default	Description
`from`	—	Source language (BCP 47: `uk`, `en`, `de`, `pl`, …)
`to`	—	Target language
`translate_items`	`true`	Translate item names after `find_or_create` resolves
`translate_groups`	`true`	Translate group names after `group_path` resolves
`translate_tags`	`true`	Translate tag values after tag assignment

Translation is only active when both from and to are set and the LLM translation service is enabled in abrest.yaml. Each entity is translated at most once (keyed by (entity_type, entity_id, lang) in CR_TRANSLATIONS).

`fields`

The heart of the config. Each key is the internal DB column name (uppercase Firebird convention). The value is an object describing where the data comes from and what to do with it.

Four field kinds exist, determined by which sub-keys are present.

Kind 1 — `source` (column mapping)

Maps a file column to a DB field.

PRICE:
    source: "Ціна"
    type: number

Key	Required	Description
`source`	yes	Exact file column header (case-sensitive)
`type`	no	`number` or `integer` — strips non-numeric characters and converts; returns `0` on failure
`tag`	no	After `TOVAR_ID` resolves, assign this field's value as a tag under the given tag name

Kind 2 — `value` (constant or computed)

Produces a fixed or computed value with no source column.

IMPORT_DATE:
    value: today
    tag: IMPORT_DATE

STATUS:
    value: 1

Key	Required	Description
`value`	yes	A literal constant, or the special keyword `today` (produces today's date as `yyyy-mm-dd`)
`tag`	no	Same as for `source` fields

Kind 3 — `resolve: group_path`

Resolves (or creates) a chain of R_GROUPS nodes from root to leaf, by (NAME, PARENT). Writes the leaf group ID into the field. Hierarchy detection (group rows in the file) is also configured here.

GROUP_ID:
    resolve: group_path
    levels:
        - name: category
          tag: CATEGORY
          detect:
              column: 0
              method: single_value
        - name: subcategory
          detect:
              method: merged_cells
    categories:
        depth: 1
        default: tag
        default_tag_name: Subcategory
        mapping:
            - source: "House brand"
              action: map
              group_id: 42

`levels`

An ordered list from highest (root-nearest) to lowest. Rules must be ordered highest level first. Each level:

Key	Required	Description
`name`	yes	Internal key used in `MappedRow` to hold the current group name. Matching a higher level resets all lower-level names.
`tag`	no	After `TOVAR_ID` resolves, assign this level's group name as a tag under the given tag name
`detect`	yes	How to recognise group rows for this level (see below)

`detect`

Key	Default	Description
`column`	`0`	Column index for structural and attribute checks
`method`	`single_value`	Detection method (see table below)
`outline_level`	—	Row outline level (XLSX only), used with `outline_level` method
`bg_color`	—	Cell background colour `RRGGBB` or `AARRGGBB` (alpha ignored)
`font_color`	—	Same format
`font_size`	—	Points, ±0.01 tolerance
`font_name`	—	Case-insensitive
`bold`	—	`true`/`yes`/`1` or `false`/`no`/`0`
`italic`	—	Same values

Detection methods

Method	Condition
`single_value`	Row has ≤ 1 non-empty cell. Cell attributes are AND-ed if present.
`merged_cells`	Cell at `column` spans more than one column (XLSX/XLS). Falls back to `single_value` for CSV/XML.
`formatting`	No structural requirement — match is purely by cell attributes at `column`. Use when category rows fill the same columns as data rows but differ in styling.
`outline_level`	Row's outline level equals `outline_level` AND is `single_value` or `merged_cells`.

`categories`

Optional per-category overrides layered on top of the group path resolution. Use it to map supplier categories to internal groups, skip branches, or convert category levels to tags.

categories:
    depth: 2
    default: tag
    default_tag_name: Subcategory
    default_group_id: 0
    mapping:
        - source: "House brand"
          action: map
          group_id: 42
        - source: "Legacy products"
          action: exclude

Key	Description
`depth`	Levels `1..depth` without an explicit mapping get `create`. Levels deeper than `depth` without an explicit mapping get `default`. `0` = all levels get `create` unless overridden.
`default`	Action for deep levels with no explicit mapping. One of `create`, `map`, `tag`, `inherit`, `exclude`.
`default_tag_name`	Used when `default: tag` and the mapping entry has no `tag_name`.
`default_group_id`	Used when `default: map` and the mapping entry has no `group_id`.
`mapping`	Exact-match (case-insensitive) per-source overrides.

Each mapping entry:

Key	Required for	Description
`source`	all	Category name as it appears in the file.
`action`	all	`create`, `map`, `tag`, `inherit`, or `exclude`.
`group_id`	`map`	Existing `R_GROUPS.ID` to use in place of a newly created node.
`tag_name`	`tag`	Tag name (auto-created in `TAG_NAMES` if missing) under which the segment value is recorded.

Actions

Action	Effect
`create`	Find-or-create the segment under the current parent; it becomes the parent for the next segment.
`map`	Use the explicit `group_id` as the parent. `group_id = 0` aborts path resolution; item is not placed.
`tag`	Segment is skipped in the path; after item resolution the value is assigned as a tag.
`inherit`	Traversal stops; the item lands in the last resolved parent.
`exclude`	The entire row is dropped — no DB insert, no tags, no translation. Logged to the skipped-rows list.

Kind 4 — `resolve: find_or_create`

Supplier-aware item resolution. Writes the resolved R_TOVAR.ID into the field.

TOVAR_ID:
    resolve: find_or_create
    name_source: "Назва товару"
    ean_source: "Штрихкод"
    article_source: "Артикул"

Key	Required	Description
`name_source`	yes	File column header whose value is the item name
`ean_source`	no	File column header for EAN13 barcode
`article_source`	no	File column header for supplier article code

Resolution order: 1. IMPORT_GETITEM — lookup by EAN13 + article + name in CR_TOVAR_ARTICLES, scoped by EXT_CONTRAGENT from the request header. 2. If translation/embedding is enabled and step 1 returned nothing: semantic match via embeddings (LLM-verified). On a confirmed match the existing item is reused and CR_TOVAR_ARTICLES is augmented. 3. Otherwise: IMPORT_SETITEM creates a new R_TOVAR inside the group resolved by the preceding GROUP_ID field (if GROUP_ID = 0, falls back to name-only create without CR_TOVAR_ARTICLES).

The tovar_type used when creating a new item comes from global.tovar_type (default 1).

Processing order reference

Find header row — first row containing every column referenced in source, name_source, ean_source, article_source fields.
For each subsequent row:
If it matches any levels[*].detect rule, update the group state for that level (and clear all lower levels) and continue — the row is not imported.
Map source columns to internal keys; overlay current group values.
Apply type: number conversions and value: substitutions.
Resolve group_path fields. If a categories action is exclude, the row is dropped.
Resolve find_or_create fields (item creation happens here, before the DB insert).
Apply tag assignments — tag: on fields/levels, plus category-derived tags.
Run global.translation against the row's item, groups, and tag values.
Build the insert payload and insert into the body table.

Abrest Import — Configuration Reference

Complete example

Top-level keys

global

global.translation

fields

Kind 1 — source (column mapping)

Kind 2 — value (constant or computed)

Kind 3 — resolve: group_path

levels

detect