🏷️ Item characteristics and item groups

An item can carry typed characteristics, the way a web shop lists them: «Grade: White · Weight: 1 kg · Packaging: Paper bag». Which characteristics an item asks for comes from a template. The item takes it from its own field, else from its item group, walking up the group tree. Key characteristics are part of the SKU. They build the item's name, stop a second item with the same values, and drive «Copy with other values».

← Business wiki

The objects#

The characteristic dictionaries belong to the Common model, so a model that does not know items can use the engine too. Their menu items sit in Inventory, next to the items that use them; Common has no characteristics group of its own.

One SKU per combination: «Sugar, White, 1 kg» and «Sugar, White, 2 kg» are two items, each with its own stock and prices. Characteristics describe an item; they do not split its balance.

Value types#

The display follows the user's interface language: «Yes» in English and its Ukrainian equivalent in Ukrainian, «2.5» or «2,5». An option is stored by its id, so renaming «White» to «White crystal» renames it on every item at once.

Where an item's template comes from#

The first one that is filled wins:

1. the item's own Characteristic template;
2. its Item group's Template for its items;
3. the parent group's Template for its items, and so on up to the root of the group tree.

The tab says where the template came from: «Own template of this record» or «Template from Item group: Grocery».

Example on the test stand:

• Item «Sugar 1kg» in group Grocery → template «Grocery».
• Move the item to a new subgroup «Sugar» under Grocery, which has no template of its own → still «Grocery», taken from the parent group.
• Give the item its own template «Sweets» → «Sweets», whatever the group says.

An item group has no characteristics of its own: the field there is the template of its items, and its card has no Characteristics tab.

Setting up: the two cards#

The characteristic card asks only for what its value type needs. A one-line explanation of the type appears under Value type. Unit shows for Integer, Decimal and Range. Decimal places shows for Decimal and Range. Values from dictionary shows for Reference, as a list of the tenant's dictionaries by name. Options of an Option / MultiOption characteristic are added on the Options tab on the right.

The template card edits its lines in one table, Characteristics of the template:

+ Add characteristic adds a line; Save lines stores the table. A characteristic twice in one template is refused, and so is a key line parameter.

Templates based on templates#

A template can be based on another: «Grocery» based on «Food». The base's lines come first, then the template's own lines. A line of the template for a characteristic the base already asks overrides the base's line in place. It can, for example, make a base characteristic required or key, or move it to another section. Changing the base changes every template built on it. Templates can chain to any depth, but not in a circle: «Food» based on «Grocery» based on «Food» is refused with Шаблони утворюють коло: базовий шаблон зрештою будується на цьому ж шаблоні.

On the template card, the base's lines are listed first, greyed, with «from Food». They are edited on the base's card. An own line that overrides one is marked «overrides the base».

Template lines#

Template «Grocery», based on «Food»:

• Section groups the lines on the card. Lines without a section go under «General».
• Required warns, it does not block. A missing value is marked and listed in the preview, for example «Missing: Weight». A catalogue is filled item by item, and a save refused over one missing value would lose the others.
• Role 1 (line parameter) is a characteristic asked on the document line, not on the item: the tint of paint mixed to order, a packing request. The item card shows it as «Asked on the order line»; see Line parameters.

Key characteristics: the SKU#

These rules apply when an item has a Base name and every key characteristic of its template has a value:

• The name is built. Name = Base name + «, » + the key values in template order. Base name «Sugar», Grade White, Weight 1 → «Sugar, White, 1 kg». Changing the base name to «Sugar crystal» renames the item at once: «Sugar crystal, White, 1 kg». Names use the tenant's default number format (a decimal comma: «2,5 l»), whatever the user's interface language.

• A duplicate is refused. Another item with the same template, the same base name and the same key values cannot be saved. The message names the item that already exists:

  Такий запис уже є: «Sugar, White, 1 kg» (17963) — те саме базове найменування і ті самі ключові характеристики.

• Copy with other values. This creates a new item with the same fields and the same non-key characteristics (Packaging, Country, Shelf life…). Its key values are empty, and its name is the base name. Fill Weight = 2 and save: the new item is «Sugar, White, 2 kg».

Without a base name, or without key characteristics in the template, the name is left exactly as typed and nothing is checked for duplicates.

Migration acceptance#

Price-list sections and inclusion labels describe an existing item; they are not automatically SKU keys. For a migration, use non-key properties unless the agreed source mapping explicitly defines a variant. Keep separate source hierarchies as separate references, even when their labels match. Preserve the item's resolved template, including inheritance up its item-group tree, and its existing required/key flags.

For example, adding 8 descriptive properties to an item with 2 existing key properties must not create 8 additional SKU keys or rename the item. Verify filled values on real item sheets, not just the presence of 8 empty definitions. An unresolved source option is a migration exception to repair, not permission to clear an existing value or invent a replacement.

Line parameters on document lines#

A line of any document whose lines point at an item (sales order, invoice, purchase order, stock documents) has a Line parameters button (the sliders icon) once the line is saved. It opens the line parameters (Role 1) of the item's template, and the value is stored on that line, not on the item.

Example: template «Grocery» gets the line «Packing request» (String, Role 1, section Order). On sales order № 2757, line «Sugar, White, 1 kg», the user enters «Two bags of 500 g instead of one». The item stays as it was; the next order line of the same item asks again.

• A line whose item has no line parameters opens a dialog that says so.
• Values on a line of a posted (read-only) document show but cannot be changed.
• Line parameters follow the document chain: a quotation line's parameters go to the order line made from it (Convert to order), and an order line's to the sales realization line (Approve). On the example, approving order № 2757 gives its realization line «Sugar, White, 1 kg» the same «Packing request: Two bags of 500 g instead of one».
• The printed quotation, order and sales realization show a line's parameters after the item, in the language of the print: «Sugar, White, 1 kg (Packing request: Two bags of 500 g instead of one)». A line with no values prints the item alone.
• Deleting a document leaves its lines' values for one night: the job PurgeCharacteristicValues (Common, 04:15) deletes values whose record no longer exists.

Characteristics in the item list#

In the item list, Column setup → Computed → Characteristic offers one column per characteristic: «Characteristic: Grade», «Characteristic: Weight». The choice is personal, like the rest of the column setup. Sorting and filtering work like any column, over the loaded rows.

• An Integer or Decimal characteristic comes as a plain number, without its unit, so that 2 sorts before 10.
• Every other type shows as on the shop page: «White», «5–25 °C».
• An item without the value, or without the characteristic in its template, is empty.

The sales-agent phone reads the same properties from the CachedCharacteristics pull (formatted captions, values, sections, option colour). It does not rebuild the SKU name and does not treat a line parameter as a property of the item. See Mobile client.

Names in other languages#

The names users see are translatable, like a country's name: a characteristic's Name and Unit, an option's Name, a template's and a section's Name. Fill the translations with the translate icon in the field. The card, the preview and the list columns then show them in each user's language. The words the engine adds follow the language too: «Yes» / Да / Так, and «2.5» / «2,5».

An item group's Name is not translatable: it shows as typed in every language.

A value without a translation shows its base text. The item's name built from the key characteristics is written in the base language («Sugar, White, 1 kg»), because the item name is one text for everyone.

Changing the template#

Values are never deleted by a template change. A value whose characteristic is not in the new template stays under «Outside the template», and the user removes it there with the bin icon. Switching back brings it into the template again. Deleting an item deletes its values.

What's not there yet#

• The item list loads a window of rows and fetches the next window as you scroll or search. A characteristic column is calculated for the loaded window, so sorting or filtering by it does not search the whole catalog.
• The sales-agent phone does not edit characteristics and does not fill line parameters on an order line.
• The engine serves any dictionary with a CharacteristicTemplate field; only items have one.

Same topic for other readers: User · Developer

Where next#

• Fill item characteristics (user)
• Characteristics for developers
• Pricing: prices are per SKU, by price type