References and collections

A navigation property (reference or collection) can be defined on the entity view. In this case, we are talking about embedded reference/collection. When the entity view is called (via the APIs or via the UI view), a single request will be made to feed the complete object composing the entity view: the principal element with all its navigation properties. And this is done recursively.

It can be bound to a navigation property of the entity or have no source. In this case, it will be fed into the Retrieved event of the entity view.

Filter an embedded collection

An embedded collection can be filtered directly on the entity view property by using CollectionFilter.

This feature lets you keep the parent item in the result while reducing the content of the embedded collection.

For examples, requirements, and limitations, see Filter embedded collections in entity views.

Editable references

A reference can have its properties edited by setting Has editable properties to true. This allows modifying the properties of the referenced entity when creating or updating the parent entity.

Required references

Required references with editable properties are fully supported in both API and UI views.

Optional references (API only)

Important

Optional (non-required) references with editable properties are supported for API scenarios only.

If a UI view attempts to use an entity view containing an optional reference with Has editable properties set to true, a generation error will occur.

This feature is useful for:

Data import: Import data using business identifiers where the related entity may or may not exist
Partner APIs: Expose APIs that accept optional related data
System integration: Handle data exchange where related entities are not always provided

Configuration

In Neos Studio, set Has editable properties to true on the optional reference property of the entity view.

For a working example, see the AKCustomerWithEditableProductCategoryByNaturalKeyView entity view in the TechnicalDemos cluster, module AlternateKeys:

# EntityViewProperties/AKCustomerWithEditableProductCategoryByNaturalKeyView.yml
- Name: PreferredProductCategory
  Caption: Preferred product category
  HasEditableProperties: true
  Source: PreferredProductCategory
  RelatedEntityViewName: AKProductCategoryByNaturalKeyView

Limitations

Warning

UI views cannot use entity views with optional editable references.

If you try to create a UI view that uses an entity view containing an optional reference with HasEditableProperties: true, a generation error will occur:

"The UI view 'MyUI' cannot use the entity view 'MyView' because it contains the non-required editable reference property 'OptionalRef'."

If you need editable references in a UI view, ensure the reference is required.

API usage

When using the API, you can POST or PUT data with the optional editable reference:

{
  "code": "CUST001",
  "name": "Customer Name",
  "preferredProductCategory": {
    "code": "CAT001",
    "name": "Category Name"
  }
}

If preferredProductCategory is set to null or omitted from the request, the reference is cleared (the foreign key is set to null).

For more details on using editable references in UI views, see UI view references.

Triggering server rules on the entity view

When the content of a navigation property has changed, it is possible to determine whether or not we want the server rules (validation rules and event rules) to be triggered on the parent even if it has not been modified.

For this, the Modification state propagation property is present on the navigation property to determine the behavior.

Let's take the example of an OrderView entity view which contains an OrderDetails collection :

Modification state propagation property = true : when you change the quantity on an OrderDetails line, the validation and event rules set to OrderView will be triggered.
Modification state propagation property = false : when you change the quantity on an OrderDetails line, the validation and event rules set to OrderView will NOT be triggered.

Note

The property is only available if the navigation property content can be changed. It is therefore not possible to modify it on an embedded reference for which the properties are not editable.

Table of Contents