Table of Contents

Alternate keys in entity views

Alternate keys can be used in entity views in two main ways: as the key of the entity view itself, or to reference associated entities through their alternate key properties.

Using an alternate key as entity view key

An alternate key can be used as the key of an entity view instead of the traditional primary key.

Declaration

To use an alternate key as the entity view key, specify the EntityAlternateKeyName property:

Description: AK product by natural key view
EntityAlternateKeyName: NaturalKey
EntityName: AKProduct

Properties behavior

When an entity view uses an alternate key:

  • The primary key is no longer required: Primary key properties (e.g., ID) are not necessarily exposed
  • Alternate key properties become required: All properties composing the alternate key must be present in the entity view

Example API response:

Traditional entity view (primary key):

{
    "productID": 301,
    "categoryID": 53,
    "code": "LAPTOP-PRO",
    "name": "Professional Laptop",
    "rowVersion": "AAAAAAAAB9H="
}

Entity view with alternate key (using NaturalKey composed of CategoryID + Code):

{
    "categoryCode": "ELECTRONICS",
    "code": "LAPTOP-PRO",
    "name": "Professional Laptop"
}

Notice that the entity view based on alternate key exposes categoryCode (from the alternate key) instead of categoryID, and has no productID or rowVersion.

Handling nullable values

If the alternate key contains non-required (nullable) properties, the entity view will only return records with a valid and complete key (all alternate key properties with a non-null value).

No concurrency management

Entity views based on alternate keys are designed for import scenarios and communication with partners. To simplify these use cases, they do not manage concurrent access and therefore expose no RowVersion property.

Referencing entities through alternate keys

Alternate keys can also be used to reference associated entities in an entity view properties.

Traditional reference (by foreign key)

- Name: CustomerID
  Source: CustomerID

API response:

{
    "orderID": 1001,
    "customerID": 42,
    "date": "2025-11-02",
    "rowVersion": "AAAAAAAAB9E="
}

Reference using alternate key

- Name: CustomerCode
  Caption: Customer code
  QuickSearch: true
  Source: Customer.Code

API response:

{
    "orderNumber": "ORD-2025-001",
    "customerCode": "ACME-CORP",
    "date": "2025-11-02"
}

In this example:

  • Customer.Code references the Code property of the Customer entity
  • Code must be a property of an alternate key of the Customer entity
  • The entity view exposes customerCode (business identifier) instead of customerID (technical key)
  • No rowVersion property is present

Complex scenarios with nested foreign keys

Alternate keys support complex scenarios where the alternate key property itself references a foreign key. For example, consider the AKProduct entity which has a composite alternate key NaturalKey composed of:

  • CategoryID: a foreign key to AKProductCategory
  • Code: a scalar property

You can reference this composite key from another entity view and even access nested properties through the foreign key:

- Name: ProductCategoryCode
  Caption: Product category code
  QuickSearch: true
  Source: Product.Category.Code
- Name: ProductCode
  Caption: Product code
  QuickSearch: true
  Source: Product.Code

API response:

{
    "orderDetailID": 5001,
    "productCategoryCode": "ELECTRONICS",
    "productCode": "LAPTOP-PRO",
    "quantity": 5
}

In this example from AKOrderDetailByNaturalKeyView:

  • Product.Category.Code navigates through the Product reference, then through its Category foreign key, to access the Code property
  • Product.Code directly accesses the Code property of the Product alternate key
  • Both properties are part of the Product composite alternate key (CategoryID + Code)
  • The system resolves ProductID by matching both Product.Category.Code and Product.Code against the AKProduct alternate key

This demonstrates that alternate keys can handle complex hierarchical scenarios where you reference entities using properties from nested relationships.

Two-way binding

The binding between alternate key properties and foreign keys is bidirectional:

  1. On save: Before the Saving event is triggered, automatic processing initializes the foreign key (CustomerID) from the alternate key property (Customer.Code)
  2. IDs are up to date in Saving: During the Saving event, the ID properties of referenced entities are already populated

Important limitation

If you modify an entity view property bound to an alternate key in the Saving event, the associated foreign key will not be automatically updated. This update must be performed manually in your code.

Example:

// ⚠️ Warning: Modification in Saving requires manual update
public Task OnSavingAsync(ISavingRuleArguments<IAKOrderByNaturalKeyView> args)
{
    foreach (IAKOrderByNaturalKeyView order in args.CreatedAndModifiedItems)
    {
        order.CustomerCode = "NEWCODE";
        // CustomerID will NOT be automatically updated
        // You must update it manually if necessary
    }

    return Task.CompletedTask;
}

Collections and references

Alternate keys work with entity view collections and references, whether editable or not.

Editable collections

Collections based on alternate keys can be modified (add, delete, modify elements). Two-way binding also applies to collection elements.

Editable references

References can be modified using alternate key properties. The system automatically resolves the corresponding foreign keys.

Best practices

When to use alternate keys in entity views?

Alternate keys in entity views are recommended for:

  • Data import: Import data using business identifiers rather than technical keys
  • Partner APIs: Expose APIs that use business identifiers understandable by external systems
  • System integration: Facilitate data exchange with systems that use different identifiers

When NOT to use alternate keys?

For standard user interfaces, it is strongly recommended to use:

  • Entity views based on the primary key
  • Scalar properties based on primary keys

Alternate keys add additional complexity that is generally not justified for typical user screens.

See also