Skip to content
MoltaroMoltaroMoltaro Docs

Projection

A projection entity publishes one unified record type over several source entity definitions. The classic example: separate Product, Service, and CustomOffering entities projected into one Offering entity so screens, references, and reports can treat them as one list.

Each projection row points to exactly one source record through one member reference field. Opening a projection row opens its source record.

What the Projection tab configures

Section titled “What the Projection tab configures”
  • Target references (members) — one member reference per source entity definition. These define which source types the projection unifies.
  • Field mappings — per member, map a source value to a projection field or to the projection’s display name or subtitle. Values are copied from the source record.
  • Synchronization — projections stay synchronized automatically; the tab shows source versus projection row counts and any issues, and offers a manual rebuild with detailed counters.

Configuration workflow

Section titled “Configuration workflow”
  1. Create a normal data entity definition (the projection, e.g. Offering).
  2. Add ordinary fields the projection should carry: DisplayCode, Price, Currency.
  3. Add one single-value Reference field per source (e.g. ProductRef, ServiceRef). These become the member reference fields.
  4. Enable projection and select the member reference fields (at least two).
  5. Configure one mapping group per member.
  6. Save, then run the initial rebuild from the Synchronization card.

Member reference field rules: the field must sit on the projection’s primary table, be a single-value Reference (not multi-value), and point to a standalone data entity — not a part, an association, or another projection (projection-on-projection is not supported). Once selected, the field becomes projection-managed: it is a storage link, hidden from ordinary forms and not user-editable.

Mapping semantics

Section titled “Mapping semantics”

A mapping copies one source value when the member’s row synchronizes:

  • Target — a projection field (Field + target field), or the projected DisplayName / Subtitle presentation values (no target field).
  • Source path — ordered field-key segments from the source row, e.g. ["Price"] or ["Category", "DisplayName"]; intermediate segments must be single-value references.
  • Transform — Copy is the only transform in this version; no expressions or functions inside mappings.

Give every member a DisplayName mapping; members without one fall back to the source record’s own display name. The projection’s system record number is technical only — map the source number into an ordinary field such as DisplayCode when users need it.

Row lifecycle

Section titled “Row lifecycle”

Projection rows are system-managed. Direct create, update, delete, archive, import, and bulk mutations against the projection entity are rejected with a business error; changes to source records drive synchronization (including archive/restore and delete). Mapped target fields are read-only at runtime — the source row stays the source of truth.

Enabling projection runs a preflight scan and rejects inconsistent existing rows; the Synchronization view computes live consistency counters (missing, stale, duplicated rows) and offers a rebuild that reconciles everything.

Configuration API

Section titled “Configuration API”

Projections are managed through four operations of the Configuration API: read and replace the configuration, check synchronization, and rebuild rows. The update replaces the full member and mapping configuration in one call.

When to use a projection

Section titled “When to use a projection”

Use a projection when several record types must appear as one — a shared selector, one combined list, one reference target — while each source keeps its own schema, logic, and governance. If the types genuinely share structure and rules, consider one entity definition instead.

Where to go next

Section titled “Where to go next”