Choosing Between User-Defined Fields and Custom Tables

TABLE OF CONTENTS

Overview

Use a User-Defined Field (UDF) when you need one extra value on a record Znode already has, such as a store, user or account. Use a Custom Table when you need your own list of data, with many rows, that you maintain separately.

A quick test:

  • If you'd say "every store, user or account has one X", use a User-Defined Field.
  • If you'd say "we keep a list of X", use a Custom Table.
  • If the data drives search lists, filters or data-driven components such as ListPages, prefer a Custom Table wherever it applies.

What each feature is

User-Defined Fields

Where: Dev Center > User-defined Fields > Attributes.

User-Defined Fields are extra fields an admin adds to records Znode already has. They're available on many record types, including:

  • Store, User and Account
  • Content Containers, Form Builder and Global Settings
  • Voucher, Banner, Blog/News, Brand and Catalog
  • Email/SMS Templates, Inventory, OMS and others

Each field has a code, a label and a data type. It can be required or translated per language. Fields are organised into Attribute Groups and Families.

You manage them in the Admin and through the API (v1 and v2). The webstore, Commerce Portal and B Store app don't manage the fields, but they can show the values.

Custom Tables

Where: Dev Center > Custom Tables.

A Custom Table is a new table you design yourself. You give it a key and a name and add fields. Then you add, edit, delete, import or export records.

Admins can create, rename and delete Custom Tables and fully control their fields. You work with them in the Admin and through the Custom Table API, for example POST /v1/custom-tables.

Custom Tables don't appear on the webstore, Commerce Portal or B Store app. PIM > Product Information Overrides runs on the same engine, as a built-in system table.

User-Defined Fields: pros and cons

Pros

  • Stored on the record. The value comes back whenever the store, user or account is read, so there's no separate lookup or extra code.
  • No development needed. Admins create fields in Dev Center without schema changes or custom APIs.
  • Built-in validation. Fields support data types, required fields and per-language translations.
  • Organised. Attribute Groups and Families keep related fields together on Admin forms.
  • Integration-friendly. ERPs and other systems read and write values through the record's own API.
  • Real-time events. The UserDefinedField event in Data Exchange works, so other systems can react to changes.
  • Can appear on the webstore. For supported record types, values can be shown to shoppers.
  • Proven at scale. Widely used today, for example for Global Settings, Store and Form Builder configuration.

Cons

  • One value per record. A field can't hold a list. Comma lists or JSON in a text field are hard to search, validate and import.
  • Only for existing record types. You can't use them to model a new kind of data.
  • Not built for search lists and filters. Values are stored with their parent record, so querying, filtering and listing across many records is slower and harder to scale than with a Custom Table.
  • Bulk import depends on the module. Values import only through the record's own import, where that module has one.
  • Can get crowded. Many fields on one record type make forms and integrations harder to manage.

Custom Tables: pros and cons

Pros

  • Holds lists. Many rows of your own data, such as lookups, schedules and mappings.
  • Best for search lists, filters and data-driven components. Independent data structures allow more efficient querying, so components such as ListPages search and filter faster and scale better.
  • Virtual relationships. Virtual foreign keys let you relate Custom Table records to each other and to Znode records without changing core tables.
  • Easier to maintain. The data lives in its own structure, separate from core records, so it can grow and change without crowding them.
  • Fully configurable. Admins create, rename and delete tables and define their fields, with field types and unique fields.
  • Built-in import and export. Business users can keep reference data current with bulk files.
  • Its own API. Integrations and ERPs read and write records through the Custom Table API.
  • No coding to set up. Tables are created in Dev Center, on the same engine Znode uses for Product Information Overrides.

Cons

  • Not automatically attached to a record. Rows don't come back when a store, user or account is read. Use a virtual foreign key and look them up.
  • Admin and API only. There's no webstore, Commerce Portal or B Store screen. Showing the data to shoppers needs a custom API endpoint (Custom API SDK) and a webstore component.
  • No real-time events. CustomTableData can be selected in Data Exchange but doesn't run. Poll the Custom Table API instead.
  • Relationships aren't enforced by the database. Relationships are virtual, so your process must keep references valid. Enforced primary and foreign keys aren't available in current releases.
  • API access needs care. Field APIs don't enforce the protections the Admin applies to system tables, so limit Custom Table API access to trusted users and systems.

Side-by-side comparison

NeedUser-Defined FieldCustom Table
One extra value per existing recordBest fitOverkill
A list with many rows (lookup, schedule, mapping)Not supportedBest fit
Search lists, filters, data-driven components (e.g. ListPages)Not recommendedPreferred: faster querying, scales better
Value comes back when the record is readYes, stored on the recordNo, looked up separately
Tied to a store, user or accountAutomaticThrough a virtual foreign key
Relationships between dataNot applicableVirtual foreign keys (not database-enforced)
Validation, required fields, translationBuilt inField types and unique fields
Bulk import and exportThrough the record's import, where availableBuilt in
Integration or ERP accessThrough the record's APIThrough the Custom Table API
Shown to shoppers on the webstoreValues can show, for supported recordsNeeds custom front-end work
Real-time Data Exchange eventsSupportedNot supported; poll the API
Maintainability as data growsFields crowd the parent recordIndependent structure, easier to maintain
Setup effortConfiguration onlyConfiguration, plus code to connect it to records

How to decide

Ask these questions in order and stop at the first "yes".

  1. Will the data drive search lists, filters or data-driven components such as ListPages? Prefer a Custom Table wherever it applies.
  2. Is it one value that belongs to a record Znode already has? Use a User-Defined Field.
  3. Is it a list of items with many rows, maintained on its own? Use a Custom Table.
  4. Must shoppers see it on the webstore? Prefer a User-Defined Field on a supported record. If it must be a Custom Table, plan a custom API endpoint and a webstore component.
  5. Must other systems react to changes in real time? Use a User-Defined Field, or plan for polling with a Custom Table.
  6. Will business users update it in bulk by file? A Custom Table is usually easier, unless the record's module already has its own import.

If you're still unsure, start with a User-Defined Field. It's the simpler option and needs no extra code.

Examples

ScenarioUseWhy
Customer's tax-exempt certificate numberUser-Defined Field (User or Account)One value per customer
Store's regional warehouse code or support phoneUser-Defined Field (Store)One value per store
Extra field on a form or content containerUser-Defined Field (Form Builder or Content Container)Extends an existing record
Global switch for a customisationUser-Defined Field (Global Setting)One site-wide value
Dealer or distributor list with region, address and territoryCustom TableA list of many records
ZIP code to delivery zone mappingCustom TableLookup data
Holiday calendar or rebate scheduleCustom TableDated rows maintained over time
Znode SKU to legacy ERP part numberCustom TableCross-reference data for integrations
Reference data that business users update by fileCustom TableBuilt-in import and export

Pitfalls and best practices

Avoid these mistakes

  • Using a Custom Table to add columns to an existing record. Nothing links its rows to that record, so every read needs extra code. A User-Defined Field does this for you.
  • Storing a list in a User-Defined Field. It holds one value per record. Comma lists or JSON are hard to search, validate and import.
  • Faking a list with numbered fields, such as Cert1Name, Cert1Expiry, Cert2Name. Use a Custom Table instead.
  • Planning a webstore feature on a Custom Table without front-end work. The data is Admin and API only until you build a custom endpoint and component.
  • Relying on Custom Table events. Use polling for Custom Table data.

Good practices

  • Combine both when it helps. Keep a summary value as a User-Defined Field on the record (for example, "Has active rebate = Yes"). Keep the details in a Custom Table.
  • Name things clearly. Use consistent field codes and table keys so integrations and admins can tell what each one is for.
  • Lock down API access. Give Custom Table API access only to trusted users and systems.
  • Use product attributes for catalog data. Data shoppers search or filter products by belongs in PIM product attributes, which are published to the search index. Neither option above feeds storefront search.

Current limitations

These points reflect current releases and may change. Check with your Znode contact before relying on them.

  • Custom Tables aren't on the webstore, Commerce Portal or B Store app.
  • Custom Table events don't run. The CustomTableData event in Data Exchange can be selected but doesn't fire.
  • Custom Table relationships are virtual only. Virtual foreign keys are supported, but database-enforced primary and foreign keys aren't available in current releases.
  • Webstore display of User-Defined Fields varies by record type. Confirm that your record type shows values to shoppers before you plan around it.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.