Related Table Template

The Related Table template creates tables that link to existing Business Central tables. This page explains how to configure and use related table features.

When to Use Related Template

Use the Related template for:

• Child records - Details linked to a parent
• Extensions - Additional data for existing entities
• One-to-many relationships - Multiple related records per parent
• Supplementary information - Data that belongs with an existing record

Examples

Feature	Related To	Purpose
Customer Certifications	Customer	Track customer credentials
Item Specifications	Item	Additional item attributes
Vendor Contacts	Vendor	Multiple contacts per vendor
Employee Training	Employee	Training history records

Creating a Related Table Feature

Step 1: Start Wizard

1. Open Tasks > Create new features
2. Click New Feature
3. Select DataRelated template

Step 2: Configure Feature Identity

Field	Description	Example
Feature Name	Internal identifier	"CustomerCertification"
Table Caption	User-visible name	"Customer Certification"

Step 3: Select Parent Table

Choose which existing table this relates to:

1. Click the Parent Table lookup
2. Select from available tables
3. Common choices: Customer, Vendor, Item, Employee

Step 4: Configure Relationship

Setting	Description
Foreign Key Field	Links to parent table
Automatic Filtering	Filter by current parent
Navigation	Link from parent to children

Step 5: Complete Wizard

Click Finish to create the feature structure.

Understanding the Relationship

Foreign Key

The related table includes a foreign key field that:

• References the parent table's primary key
• Validates against parent records
• Enables filtering and navigation

Example Structure

Customer Certification table:

| Field               | Type    | Description         |
|---------------------|---------|---------------------|
| Customer No.        | Code    | Foreign key to Customer |
| Line No.            | Integer | Unique per customer |
| Certification Type  | Code    | Type of certification |
| Issue Date          | Date    | When issued         |
| Expiry Date         | Date    | When it expires     |

Feature Configuration

Feature Card Settings

Field	Description
Feature	Feature name
Template	"DataRelated"
Anchor Table	The parent table this feature is related to

The foreign-key field is created as a regular feature field with Type = Lookup and Related Table = Anchor Table. There is no separate "Foreign Key Field" picker on the Feature Card.

Generated Components

Component	Purpose
Table	Stores the related records
List Page	Shows records for current parent
Page Part	Embeddable list for parent page

No card page is generated. Clicking an entry on the list page does not open a card. Related records are viewed and edited in the list page and the FactBox. This is a known limitation that may be improved in a future release.

Lookup field size can go stale

A Lookup feature field takes its text length from the field it references in the related/anchor table. If that referenced field changes, the size may fail to repopulate and the field can generate as a zero-length text type, producing the publish error:

The length for the type 'Text' must be positive

Remedy: delete and recreate the Lookup field so the size is re-read from the current related table field. See Publishing Failures.

The Anchor Key and the API

In a DataRelated (anchored) table, the anchor/parent key fields — the Code linking a row to its parent, and any Line No. — are inherited from the anchor table and managed automatically by the anchoring mechanism.

They are not regular feature fields, so they do not project onto the generated API page. Only explicitly defined feature fields (Lookup fields, FlowFields and so on) plus system fields (id, systemid, systemcreatedat) appear over the API. Enabling Add system fields to API pages adds only systemid and systemcreatedat — it does not add the anchor Code or Line No.

This is by design.

Consequence: over the API you cannot filter related-table records by their parent using the inherited anchor key, because that key is not in the projection. Power Apps, for example, reports the column as "not recognized".

Exposing the parent key over the API

The intended approach is to add a dedicated regular feature field that mirrors the anchor key — an "AnchorCode" field with Type = Lookup and Related Table = the anchor table. A regular feature field projects over the API like any other, so external consumers can filter on it.

Keep the inherited anchor key intact and add the mirror field alongside it.

Do not make the mirror field the primary key. Replacing the inherited anchor key with it lets the anchor value and the mirror value diverge, and the automatic subpage filtering breaks.

Current limitation: SOD does not yet offer a supported configuration that auto-populates the mirror field with the anchor Code on insert or modify while leaving the automatic subpage filtering and system-assigned anchor population intact. This capability is confirmed for an upcoming release, with no ETA at the time of writing.

For context on the key structure: the related table's full primary key can be a composite of [Code + Line No.], where Code is the single parent reference and Line No. distinguishes multiple rows under one parent. Only the parent Code needs to project for parent-based filtering; Line No. does not.

Adding Fields

Configure fields beyond the automatic foreign key:

Required Fields

• Foreign key (auto-created)
• Line number or secondary key

Custom Fields

Add fields specific to your data:

• Descriptive fields
• Dates
• Amounts
• Status fields

Placing Related Data on Parent Pages

FactBox Approach

Show summary in parent page's FactBox area:

1. Create a ListPart for your feature
2. Place as FactBox on parent page

Subpage Approach

Show detailed list on parent page:

1. Feature creates a ListPart automatically
2. Place on parent card/document page

Action Approach

Link via navigation action:

1. Add action to parent page
2. Opens related records filtered by current parent

Common Related Table Patterns

Detail Records

Purpose: Multiple detail lines per parent

Structure:

• Parent No. (FK)
• Line No.
• Detail fields

Example: Customer Notes

Customer No.  Line No.  Note Type   Note Text
CUST001       10000     General     Primary contact is John
CUST001       20000     Shipping    Requires signature
CUST002       10000     Billing     Net 30 terms agreed

Attribute Table

Purpose: Flexible attributes for parent

Structure:

• Parent No. (FK)
• Attribute Code
• Attribute Value

Example: Item Attributes

Item No.    Attribute Code   Value
ITEM001     COLOR            Blue
ITEM001     SIZE             Large
ITEM001     WEIGHT           2.5kg
ITEM002     COLOR            Red

History Records

Purpose: Track changes or events over time

Structure:

• Parent No. (FK)
• Date/Time
• Event Type
• Description

Example: Customer Activity Log

Customer No.  Date        Event Type    Description
CUST001       2024-01-15  Order         Placed order SO-1234
CUST001       2024-01-20  Payment       Received payment
CUST001       2024-02-01  Contact       Phone call with Jane

Navigation Between Tables

From Parent to Children

Users can navigate from a parent record to see related records:

1. Open parent record (e.g., Customer Card)
2. Click action or FactBox
3. See related records filtered

From Child to Parent

From a related record, navigate to the parent:

1. Click the foreign key field
2. Drill down opens parent card

Using Related Features

Creating Related Records

1. Open the parent record
2. Navigate to related data (via action, FactBox, or subpage)
3. Add new related records
4. Foreign key is set automatically

Viewing Related Records

1. Open the parent record
2. Related records display in context
3. Filtering is automatic based on parent

Editing Related Records

1. Access via parent navigation
2. Edit directly in the list page or FactBox — there is no card page for a DataRelated feature
3. Changes save automatically

Best Practices

Foreign Key Naming

Name the foreign key clearly:

• "Customer No." for Customer relations
• "Item No." for Item relations
• Follow BC conventions

Secondary Keys

Include a line number for:

• Multiple records per parent
• Ordering records
• Unique identification

Denormalization

Consider including parent info:

• Parent Name (for display)
• Relevant parent attributes
• Reduces joins for reporting

Related Topics

• Features Overview
• Feature Templates
• Data Table Template
• Document Table Template