TABLE OF CONTENTS
- Overview
- What each feature is
- User-Defined Fields: pros and cons
- Custom Tables: pros and cons
- Side-by-side comparison
- How to decide
- Examples
- Pitfalls and best practices
- Current limitations
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
| Need | User-Defined Field | Custom Table |
|---|---|---|
| One extra value per existing record | Best fit | Overkill |
| A list with many rows (lookup, schedule, mapping) | Not supported | Best fit |
| Search lists, filters, data-driven components (e.g. ListPages) | Not recommended | Preferred: faster querying, scales better |
| Value comes back when the record is read | Yes, stored on the record | No, looked up separately |
| Tied to a store, user or account | Automatic | Through a virtual foreign key |
| Relationships between data | Not applicable | Virtual foreign keys (not database-enforced) |
| Validation, required fields, translation | Built in | Field types and unique fields |
| Bulk import and export | Through the record's import, where available | Built in |
| Integration or ERP access | Through the record's API | Through the Custom Table API |
| Shown to shoppers on the webstore | Values can show, for supported records | Needs custom front-end work |
| Real-time Data Exchange events | Supported | Not supported; poll the API |
| Maintainability as data grows | Fields crowd the parent record | Independent structure, easier to maintain |
| Setup effort | Configuration only | Configuration, plus code to connect it to records |
How to decide
Ask these questions in order and stop at the first "yes".
- Will the data drive search lists, filters or data-driven components such as ListPages? Prefer a Custom Table wherever it applies.
- Is it one value that belongs to a record Znode already has? Use a User-Defined Field.
- Is it a list of items with many rows, maintained on its own? Use a Custom Table.
- 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.
- Must other systems react to changes in real time? Use a User-Defined Field, or plan for polling with a Custom Table.
- 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
| Scenario | Use | Why |
|---|---|---|
| Customer's tax-exempt certificate number | User-Defined Field (User or Account) | One value per customer |
| Store's regional warehouse code or support phone | User-Defined Field (Store) | One value per store |
| Extra field on a form or content container | User-Defined Field (Form Builder or Content Container) | Extends an existing record |
| Global switch for a customisation | User-Defined Field (Global Setting) | One site-wide value |
| Dealer or distributor list with region, address and territory | Custom Table | A list of many records |
| ZIP code to delivery zone mapping | Custom Table | Lookup data |
| Holiday calendar or rebate schedule | Custom Table | Dated rows maintained over time |
| Znode SKU to legacy ERP part number | Custom Table | Cross-reference data for integrations |
| Reference data that business users update by file | Custom Table | Built-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.