↑↓ selectEnter openEsc close

    1. Elbuz

    How to add your own field to products, contacts and documents

    17 min readUpdated

    Add your own field to products, contacts, documents and other tables: it shows up in the card, grid, filters, formulas and exports like a built-in field.

    When you need this:

    • A second purchase price or an old price — a “Price” field becomes a catalog column for formulas and markups.
    • A specific supplier's price — the batch update copies it from the price list into your field.
    • A value a formula calculates — “Read Only” blocks edits by hand and via the API.
    • An internal mark — a “Flag” field gives a checkbox column to filter by.

    Where to start: “Table settings” → table → “Add field”.

    What custom fields can do

    Which tables you can add a field to

    A field isn't added to the app as a whole — it goes into a specific table:

    • “Products (base catalog)” — the most common case;
    • “Price list products” — data that comes from the supplier;
    • “Product categories”, “Manufacturers”;
    • “Contacts”;
    • “Documents” and “Documents (items)” — the document header and its lines;
    • “Product variants (option products)”, “Messages”.

    A catalog product field and a price list product field are different fields, even if you give them the same name. Data moves from the price list to the catalog through the batch update, and for that each of the two fields must exist in its own table.

    How to add a field

    1. In the list, expand the table you're adding the field to — for example, “Products (base catalog)”.
    2. Click “Add field” — the app asks for the field type.
    3. Enter a name: this is what you'll see in the card, in the grid and in formula macros.
    4. Set up how the field behaves — see below — and save.

    Creating a field takes noticeable time and shows “Adding a new field, please wait...”: the app actually adds a column to the database table, registers it in the grid, sets it up for every user and creates group permissions. So every employee sees the new field right away, and you can filter by it immediately.

    All of this happens in a single request to the server, with no background job: the window waits for the response under the “Adding a new field, please wait...” message. The steps run in order:

    1. a row in the field list;
    2. a column in the database table;
    3. a grid column and every employee's grid settings;
    4. the column name for every language;
    5. group permissions.

    These steps don't share a transaction. The app doesn't check how many fields the table already has.

    What happens after you choose a type. The top-left branch is the case where the table already has a “New field” that was never renamed: nothing is created, and the app explains why. A separate branch is when the database didn't add the column: the field isn't created. “Progress bar” and “Button” don't need a database column
    YesNoNoYes — no database columnNoYesPicked a table, clicked “Add field”and chose a typeDoes this table already have a fieldnamed “New field”?No new field is created.Message: a field with this namealready exists in this tableRow in the field listType “Progress bar”or “Button”?Column in the database tableGrid columnDid the column appearin the database table?Field record removed.Red message“Operation failed!”Column in every employee's gridand column name for everylanguageGroup permissions for the fieldField row selected,name open for editing
    • Action or result
    • Decision: the path depends on the answer

    If the database didn't add the column, there will be no field. After the column step, the app checks that the column really exists in the database table. If not, the field record is removed, no new row appears in the field grid, and a red “Operation failed!” message pops up top right. Try adding the field again.

    While the table has a “New field” that was never renamed, you can't add another one. A new field is created with the name “New field”, and before creating it the app looks for a field with the same name in that table.

    If it finds one, it creates nothing — even if you chose a different type — and shows: “A field with this name already exists in this table — usually a “New field” that was never renamed. Give it its own name and add a new one.” Rename the earlier field and click “Add field” again.

    A field's type can't be changed after it's created. The type isn't editable in the field card, and renaming the type converts nothing. If you picked the wrong type, create a new field of the right type, copy the values over with a formula and delete the old one. So choose the type carefully the first time.

    Field types

    TypeWhat it's for
    Single-line textshort text up to 255 characters: a code, an SKU, a one-line note
    Textlong text with no length limit
    Numbera whole number
    Number (decimal)a number with a fractional part
    Pricea high-precision money field — the one to use for a second purchase price, an old price or another supplier's price
    Flagyes/no: a checkbox in the grid, a toggle in product and contact cards
    Lista dropdown with a set list of values: in product and contact cards you pick the value from the list
    Date / Timea date
    Image, Filean attachment with limits on file types and size
    Email, Phone, text with a format check
    Passworda value hidden behind asterisks
    a link to a record in another table by its number
    Progress bara progress bar; it doesn't store a value of its own but shows someone else's
    Buttonan action right from a table row; it doesn't store a value either

    “Single-line text” or “Text”? Choose “Single-line text” if the value is short and you'll filter or sort by it — such a field works faster and looks neater in the grid. Keep “Text” for descriptions and notes several sentences long.

    The last two types — “Progress bar” and “Button” — are virtual: they don't create a database column and store no data of their own. You can't filter, sort or export them to a file — they exist only as an interface element in the table.

    How to set up a “Button” field is covered in the article on the table button.

    Field settings

    SettingWhat it does
    Activea disabled field disappears from the interface; the data stays
    Display blockgroups fields in the list where blocks exist — in categories and price list products. In other tables a new field gets no block, and that's normal: the block doesn't affect how the field shows in a product, contact or document card.
    Processing orderthe field's position among the others
    Default valuewhat the field holds until someone fills it in. The category card shows it in any empty field, and a new product or new contact gets it when created. Existing products and contacts, documents, the batch update, formulas and the API don't apply the default value. The value must suit the field type: text in a number field is saved as 0
    Read Onlythe value is visible but can't be changed by hand — for fields a formula fills in. The batch update from price lists skips such a field, see below
    Dropdown valuesthe options for the “List” type, one per line
    Multiline, editorhow long text is edited: a plain field or an editor with formatting
    Placeholder, Tooltiphints for whoever fills in the card
    Field is full widthstretches the field across the whole card row
    Field length, Field length after decimal point“Field length” exists for all types except image, file, ID and flag; “Field length after decimal point” only for the “Number” type
    Notefor yourself: why the field was created

    Renaming a field doesn't update the macro everywhere. When you change the name, the app fixes it in catalog and price list field formulas — the macro there looks like {Product: Name}. In export templates, however, the macro keeps the old name and stops finding the field. So after renaming, check the templates that use this field.

    What overwrites a value you typed by hand

    The app doesn't separately protect a catalog product field value you typed by hand. It can be overwritten by the batch update from price lists, the field formula and product updates via the API — and each is stopped by a different setting:

    What writes to the fieldWhat it doesWhat stops it
    Batch update from a price listwrites the price list value to the field“Do not update” on the product itself — the whole product is skipped. “Update if value is empty in base catalog” — a filled-in value stays. “Update if value is not empty in price lists” — an empty value or zero in the price list doesn't wipe the field
    Field formulaevery time it's applied, overwrites the value for all products that match its condition“Do not update” on the product, and for a “Price” field also “Fixed Price” on the product. “Read Only” in the field settings does not stop the formula
    Update via the APIwrites the fields passed in the request“Read Only” — such a field isn't written
    Field links tab of the Base catalog update window showing extra-field rows with Active turned off and no price list field
    1Extra field row
    2Empty price list field
    3Active turned off
    4Update if empty in base catalog
    1. An extra field of the base catalog is listed as an ordinary row.
    2. The price list field cell is empty (shows dots), so nothing is transferred into this field.
    3. Active is turned off, so the row does not take part in the update.
    4. This option updates the value only when it is empty in the base catalog.

    Here's how “Read Only” affects the batch update:

    • such a field isn't added to the field list in the price list's update settings;
    • the update using each price list's settings and “Force update from this source” skip it;
    • the main run takes the fields from the price list settings as they are.

    If the field got there before you set the option, remove it from the price list settings yourself.

    If both a price list and a formula fill the field, the formula's result wins. In a batch update run, the app first carries over fields from price lists, then the fields from “Force update from this source”, and applies formulas last if “Apply formulas” is turned on in the settings. The “Default value” plays no part in this sequence.

    To keep your own value, set “Do not update” on the product: both the batch update and formulas will then skip it. Keep in mind that this option protects the whole product, not one field: it will no longer be updated from the price list.

    How to delete a field and why the app may refuse

    Deleting removes more than the column. Along with the field, these disappear: its column in the grid and in every employee's settings, group permissions for it, rows in export templates, this field's formulas, links to parser fields, and for price list fields also the text replacement, currency, ignore, markup and batch processing rules that referred to it.

    The app may refuse to delete the field. If the field is mentioned in a hand-written condition — an export template, saved table filter, category distribution rule, markup, trigger, promotion, configurator, smart search, email template, task board, parser or group permissions — deletion won't go through. You'll see a list of places where the field is used instead.

    This is intentional: the condition goes into the query as text, and without the column the whole operation breaks, not just that rule. The app can't fix the expression for you — removing “AND field = …” widens the selection, removing “OR field = …” narrows it. So remove the field from the listed conditions and delete again.

    Why a field sometimes can't be deleted. The arrow back isn't a dead end: you removed the mentions and clicked again
    YesNoClicked to delete the fieldIs the field used in a hand-writtencondition? — export template,filter, rule, trigger, promotion,configurator, search, parserDeletion is not performed.The app lists the placeswhere the field is usedRemove the field from thoseconditionsand delete againRemoved together with the field:grid column,employee settings, grouppermissions,template rows, formulas, parsermappingsField deleted
    • Action or result
    • Decision: the path depends on the answer

    The refusal message starts with “Field “…” is used in hand-written SQL conditions. It cannot be deleted”, and below it come the groups of places where the field was found: “Export templates”, “Saved table filters”, “Category distribution rules”, “Field formulas”, “Markups” and so on.

    So the message itself tells you where to look: open each place it names, remove the field from the condition or replace it with another one, save and delete again.

    The app's system fields can't be deleted or renamed — you can only edit the fields you created.

    Scenarios

    See a specific supplier's price in the catalog next to your own

    What to do. Create a “Price” field in the “Price list products” table and another one in “Products (base catalog)”. Then, in that price list's batch update settings, on the “Field links” tab, find the catalog field, set the price list field in the “Field name from price lists” column and turn on “Active”.

    What you get. A “Price” field stores a number with eight decimal places. After a batch update run, the value from the price list moves into the catalog field.

    What won't happen. A new catalog field appears in the field links off and with no price list field; until you set both, the batch update ignores it. “Fixed Price” on a product protects built-in prices from the batch update, not your “Price” field filled from the price list. To stop a product updating, set “Do not update”.

    A field that only a formula calculates

    What to do. Create a field in “Products (base catalog)”, tick “Read Only” in its settings card and write a formula for it.

    What you get. Product updates via the API don't write this field. Such a field isn't added to the batch update's field links, and the update using each price list's settings and “Force update from this source” skip it. The formula still writes the value as usual.

    What won't happen. “Read Only” doesn't stop the formula: it will overwrite the field for every product that matches its condition. It skips only products marked “Do not update”, and for a “Price” field also products with “Fixed Price”.

    Fill a field from the price list once, then edit it by hand

    What to do. Match the catalog field to the price list field in the batch update settings, as in the first scenario, and in the same row tick “Update if value is empty in base catalog”.

    What you get. Products with an empty field get the value from the price list. Where the field is already filled in — from the price list or by you — it stays as it is.

    What won't happen. The app treats zero as an empty value: if the product's field contains 0, the next update will write the price list value there.

    An internal mark to filter products by

    What to do. In “Products (base catalog)”, create a “Flag” field, for example “Checked”.

    What you get. A checkbox column appears in the product grid; you can filter and sort by it and export it. The column is added to every employee's grid settings.

    What won't happen. The field card has no “Default value” for the “Flag” type. All products already in the catalog get the field unchecked, and you or a formula will have to tick it.

    What to do when a field is missing or doesn't fill in

    What you seeWhyWhat to do
    The field won't delete, and a list of places is showna hand-written condition refers to itremove the field from those conditions and delete again
    The field isn't in the card“Active” is off or group permissions for the field are closedturn the field on; check group permissions
    The field isn't in the gridthe column is turned off in this employee's table settingsturn the column on in the grid settings
    The field is visible but can't be filled in“Read Only” is setclear the option, or fill the field with a formula or an import
    Export broke after renamingthe template still has the macro with the old namefix the macro in the template
    You can't enter a decimal number in the fieldthe type is “Number”, which holds whole numberscreate a “Number (decimal)” or “Price” field
    Filtering by the field doesn't workthe type is “Progress bar” or “Button” — they're virtualfor data you filter by, use a regular type
    Price list data doesn't reach the catalog fieldthese are two different fields in different tablesset up the transfer in the batch update
    A colleague can't see the fieldgroup permissions for this field are closedcheck group permissions
    The field takes long to createthe app is adding a column to a large database tablewait; with a catalog of hundreds of thousands of rows this is normal

    FAQ

    What field should I create for a second price?

    The “Price” type — a high-precision money field. Use it for an old price, another supplier's price or a price in another currency too; you can then use it in formulas, markups and exports.

    Can I change the type of a field that already exists?

    No. Create a new field of the right type, copy the values over with a formula and delete the old one.

    I want to delete my own field, but the app says it's used in hand-written SQL conditions. What do I do?

    The field is mentioned in a hand-written condition, and without the column the whole operation would stop working. The places are listed under the message: remove the field from the conditions, save and delete again (details).

    How do I add my own field to a product, say “Warranty, months”, and export it?

    Add the field to “Products (base catalog)”: “Single-line text” for the warranty as text, “Number” for the months. The field goes to a website or marketplace only if you add it to an export template.

    How is a custom field different from an attribute?

    Attributes are product properties that shoppers filter by in the storefront, and they live in their own directory. A custom field is a column in your table for internal work: codes, dates, internal prices, marks (attributes).

    I want a “Product condition” field with a dropdown: New, Used, Discounted. How do I do it?

    In “Products (base catalog)”, create a “List” field and enter the options in “Dropdown values”, one per line. If shoppers should see the condition in storefront filters, you need an attribute, not a field.

    Can I make an auto-numbered field that starts at 1000 and has the DOG- prefix?

    Not with custom fields: they have no counter or prefix. A number like DOG-1000 comes from the document type: the DOG-{N} pattern in the “Number format” column (document numbering).

    Can I tick a box so a field's value can't repeat across products?

    No, fields have no uniqueness check: you can enter the same value in as many products as you like. To find identical products, use duplicate search.

    Where to find it and who has access

    Menu
    Account → System settings → the “Table settings” tile
    What's inside
    a list of tables; expand the one you need — its fields on the left, the selected field's card on the right
    Access right
    the group permission for the “Table settings” window; each field also has its own group permissions
    Where the field appears
    card, grid, filters, formulas, export templates
    Table settings window with the Products (base catalog) table expanded and its list of fields
    1Table list
    2Add field button
    3Name column
    4Field name in database column
    5Active column
    1. The list of tables: each one is a section, and clicking it expands that table's fields.
    2. The button with the plus sign adds a new field to the selected table.
    3. The Name column shows the field name as users see it.
    4. The Field name in database column shows the technical name of the column in the database.
    5. The Active column (A) shows whether the field is turned on.

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free