Building Data Entities

What is a data entity?

Entities vs views vs tables

Creating a data entity in Visual Studio

Step-by-step: the entity wizard

1. Right-click project → Add New Item → Data Model → Data Entity
2. Primary data source: Select the root table (e.g., AxionInspectionTable)
3. Public entity name: The OData endpoint name (e.g., AxionInspections)
4. Public collection name: Plural form for OData (e.g., AxionInspections)
5. Enable public API: Yes for OData access, No for Data Management only
6. Staging table: Auto-generated (e.g., AxionInspectionStaging)

Entity properties

Backing tables and data sources

An entity can have multiple data sources (backing tables) joined together:

Data source properties

Field mapping

Each entity field maps to a specific field on a specific data source:

// Entity: AxionInspectionEntity
// Field mappings:
//   InspectionId    → AxionInspectionTable.InspectionId
//   Description     → AxionInspectionTable.Description
//   InspectorName   → HcmWorker.Name (read-only — resolved from worker table)
//   InspectionDate  → AxionInspectionTable.InspectionDate
//   Status          → AxionInspectionTable.Status
//
// InspectorName is mapped to HcmWorker (read-only data source)
// On import, the entity resolves "John Smith" → HcmWorker.RecId → stores RecId

Staging tables

Every data entity with DataManagementEnabled = Yes gets a staging table — an intermediary where import data lands before being pushed to the real tables.

Import flow

External File → Parse → Staging Table → Validate → Target Tables
                         ↓ (errors stay here)
                      Error log with row-level details

Why staging tables matter

Staging table structure

The staging table is auto-generated and mirrors the entity’s fields, plus:

• DefinitionGroup — identifies which import job this row belongs to
• ExecutionId — unique ID for this import run
• IsSelected — whether this row should be processed
• TransferStatus — Completed, Error, NotStarted

Entity methods (validation and defaulting)

Data entities support X++ methods that run during import/export:

// On AxionInspectionEntity

// Runs before each row is inserted into target tables
public boolean validateWrite()
{
    boolean ret = super();

    if (!this.InspectionId)
    {
        ret = checkFailed("Inspection ID is required");
    }

    if (this.InspectionDate > today())
    {
        ret = checkFailed("Inspection date cannot be in the future");
    }

    return ret;
}

// Maps staging fields to target table fields during import
public void mapEntityToDataSource(
    DataEntityRuntimeContext _entityCtx,
    DataEntityDataSourceRuntimeContext _dataSourceCtx)
{
    super(_entityCtx, _dataSourceCtx);

    // Custom mapping: resolve inspector name to RecId
    if (_dataSourceCtx.name() == dataEntityDataSourceStr(
        AxionInspectionEntity, AxionInspectionTable))
    {
        // Lookup logic handled by entity framework
        // when field has proper EDT and relation defined
    }
}

// Runs after insert to perform additional business logic
public void postLoad()
{
    super();
    // Post-processing after data loads from DB (for export scenarios)
}

Composite entities

A composite entity groups multiple related entities into a single unit for import/export. Think: importing a sales order header AND its lines in one file.

When to use composite entities

Structure

// Composite Entity: AxionInspectionCompositeEntity
//   Root Entity: AxionInspectionEntity (header)
//     Child Entity: AxionInspectionLineEntity (lines)
//       Link: InspectionId == InspectionId

<AxionInspection>
  <InspectionId>INS-001</InspectionId>
  <Lines>
    <Line><LineNum>1</LineNum><Measurement>4.5</Measurement></Line>
    <Line><LineNum>2</LineNum><Measurement>3.8</Measurement></Line>
  </Lines>
</AxionInspection>

Aggregate entities

Aggregate entities are read-only entities backed by aggregate measurements (pre-computed OLAP-style data from the Entity Store). They’re used for analytical scenarios, not transactional.

Entity development best practices

Vik’s checklist when building entities at Axion:

1. Natural keys, not RecIds — external systems use human-readable identifiers
2. Mark read-only data sources — joined reference tables should be read-only
3. Validate in validateWrite() — catch bad data before it reaches production
4. Test staging import — always test with the Data Management workspace, not just OData
5. Prefix custom entities — AxionInspectionEntity, not just InspectionEntity
6. Set IsPublic intentionally — only expose to OData if external systems need it
7. Handle missing lookups — if a natural key can’t be resolved, the row should fail gracefully with a clear error

Next up: Forms, Menus, and UI Patterns — build user interfaces with form patterns, menu items, and the label system.