Nested Entities

A nested entity is a repeating-row structure inside an entity type. It lets an administrator model tabular data — line items on an invoice, material entries on a job requisition, contact rows on a counterparty record — as part of the parent entity type rather than as separate records.

What this page describes is the mechanism. The specific kinds — document types, fields, statuses — are defined for your organization; yours may differ. See the entity system.

How nested entities work

A nested entity type is defined inside a parent entity type. It has its own name, machine name, and set of fields organized into groups — the same structure as a top-level entity type, but scoped to the parent.

When a user creates or edits a record of the parent entity type, the nested entity appears as a table. Each row in the table is one nested record, with columns corresponding to the nested entity type’s fields. Users can add rows, edit individual cells, and remove rows.

A parent entity type can have more than one nested entity type. For example, a document entity type might have one nested entity type for line items and another for approval signatures.

Creating a nested entity type

To add a nested entity type, open the parent entity type’s edit page and go to the Nested entities tab. Choose Create nested type, then define:

  • A display name and machine name — subject to the same rules as top-level entity types. Nested entity machine names must be unique across the organization.

  • One or more field groups, each containing one or more fields. The available data types are the same nine types described in data types.

Save the parent entity type to persist the nested entity type and its fields.

Supported data types in nested entities

Nested entity fields support the same nine data types as top-level fields: String, Integer, Decimal, Date/Time, Link, Set, Collection, Map, and Expression.

Expression fields inside nested entities are evaluated per row. A nested expression can reference other fields in the same nested row or fields on the parent record through dot-path or JavaScript syntax. See expressions for the syntax and evaluation rules.

Auto-fill on link selection also works inside nested entities. When a user selects a value in a nested link field, dependent expression fields in the same row are recalculated.

Where nested entities are available

Nested entities are available on entity types belonging to these super types:

  • Document

  • Counterparty

  • Directory

  • Task

  • Proposal

Editing and deleting nested entity types

Editing a nested entity type follows the same process as editing the parent: open the parent entity type, go to the Nested entities tab, and modify the nested type’s fields or groups.

Deleting a nested entity type removes its definition and all associated field definitions. Existing nested records in parent records that used the deleted nested entity type are no longer displayed or accessible through the interface.

The same caution that applies to deleting a field applies here: removal is permanent, and stored data for deleted nested structures becomes inaccessible.