Web API Navigation Properties
Within the CSDL $metadata document, each entity type that is not abstract will have
NavigationProperty element describes data related to the current entity type. When you retrieve a record, you can expand navigation properties to include related data.
NavigationProperty elements have the following attributes:
||The name of the navigation property. This value is case sensitive.|
||The related entity type. This can be to a single value or a collection of a type.|
||The name of the navigation property on the other side of the relationship.|
||Whether the value can be null.|
There are two types of navigation properties: single-valued and collection-valued. This distinction is important because capabilities for each type of navigation property are different.
Single-valued navigation properties
When a navigation property
Type refers to a single value, it represents a one-to-many relationship to set a reference to another table record. This is commonly called a 'lookup'. For example, this is the
createdby navigation property:
<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby"> <ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" /> </NavigationProperty>
This single-valued navigation property connects multiple
account records to a single
systemuser record. Each
systemuser record will have a collection-valued navigation property named
lk_accountbase_createdby that connects them to the
account records they have created.
These values are stored in the relationship definitions that can be accessed either using the Organization Service SDK OneToManyRelationshipMetadata or Web API OneToManyRelationshipMetadata entity type.
||The name of the single-valued navigation property.|
||The name of the collection-valued navigation property.|
We introduced lookup properties in the Web API Properties topic. See Lookup properties.
Single-valued navigation properties have a
ReferentialConstraint with a
Property attribute that refers to a lookup property. You can recognize lookup properties because they use the following naming convention:
ReferentialConstraint has a
ReferencedProperty attribute that identifies the primary key name of the related entity type.
In most cases the
<name> found in the lookup property will match the name of the navigation property, except in the case of multi-table lookups.
When the single-valued navigation property is part of a multi-table (or polymorphic) lookup there will be a single lookup property which is the
ReferentialConstraint for more than one single-valued navigation property.
An entity type may have something like the following combination where a single
_customerid_value lookup property supports multiple single-valued navigation properties that represent a multi-table lookup. There will be one single-valued navigation property for each type of table supported by the multi-table lookup.
<EntityType Name="socialprofile" BaseType="mscrm.crmbaseentity"> <Key> <PropertyRef Name="socialprofileid" /> </Key> <Property Name="_customerid_value" <!-- lookup property --> Type="Edm.Guid"> <Annotation Term="Org.OData.Core.V1.Description" String="Shows the customer that this social profile belongs to." /> </Property> <NavigationProperty Name="customerid_contact" <!-- Name different from lookup property --> Type="mscrm.contact" Nullable="false" Partner="Socialprofile_customer_contacts"> <ReferentialConstraint Property="_customerid_value" <!-- Reference to lookup property --> ReferencedProperty="contactid" /> </NavigationProperty> <NavigationProperty Name="customerid_account" <!-- Name different from lookup property --> Type="mscrm.account" Nullable="false" Partner="Socialprofile_customer_accounts"> <ReferentialConstraint Property="_customerid_value" <!-- Reference to lookup property --> ReferencedProperty="accountid" /> </NavigationProperty> </EntityType>
In these cases, setting the value of any of the single-valued navigation properties will set all the other participating single-valued navigation properties to null. The corresponding lookup property GUID value will change, but you will need to retrieve specific annotations available to know which table it now refers to. More information: Retrieve data about lookup properties.
Collection-valued navigation properties
When a navigation property
Type refers to a collection value, it represents a many-to-one or many-to-many relationship. For example, this is the account entity
Account_Tasks navigation property.
<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />
This navigation property connects an
account record to many
task records. Each
task has a single-valued navigation property named
regardingobjectid_account_task that refers to the
account as the regarding object.
The way you work with collection-valued navigation properties using OData is the same regardless of whether the relationship is a one-to-many or many-to-many relationship. Both are considered collections and you interact with them the same way.
A many-to-one relationship is the mirror image of the one-to-many relationship. It will have a partner single-valued navigation property. In the Single-valued navigation properties example above we looked at the
createdby single-valued navigation property for the
account entity type.
systemuser entity type you will find the collection-valued navigation property partner named
<NavigationProperty Name="lk_accountbase_createdby" Type="Collection(mscrm.account)" Partner="createdby" />
Name and the
Partner of the collection-valued navigation property are the same, it represents a many-to-many relationship.
Many-to-many relationships have some implementation details you can find in the service documents. For most use cases, you can ignore them.
For example, every many-to-many relationship has an intersect table which supports it. These intersect tables have entity types that typically have just 4 read-only properties. The following is an example of the
teammembership entity type which is an intersect table that supports a many-to-many relationship between
team entity types.
<EntityType Name="teammembership" BaseType="mscrm.crmbaseentity"> <Key> <PropertyRef Name="teammembershipid" /> </Key> <Property Name="systemuserid" Type="Edm.Guid" /> <Property Name="versionnumber" Type="Edm.Int64" /> <Property Name="teammembershipid" Type="Edm.Guid" /> <Property Name="teamid" Type="Edm.Guid" /> </EntityType>
You can't work with entity types that represent intersect tables directly because all the properties are read-only. Perform operations on the respective collection-valued navigation properties for each entity type. More information: Associate and disassociate table rows using the Web API
For this many-to-many relationship, the
systemuser entity type has this collection-valued navigation property:
<NavigationProperty Name="teammembership_association" Type="Collection(mscrm.team)" Partner="teammembership_association" />
team entity type has this collection-valued navigation property:
<NavigationProperty Name="teammembership_association" Type="Collection(mscrm.systemuser)" Partner="teammembership_association" />
These values are stored in the relationship definitions that can be accessed either using the Organization Service SDK ManyToManyRelationshipMetadata or Web API ManyToManyRelationshipMetadata entity type.
||The name of the collection-valued navigation property for one of the entity types.|
||The name of the collection-valued navigation property for the other entity type.|
Learn about Action Definitions.
Web API types and operations
Web API Service Documents
Web API EntityTypes
Web API Properties
Web API Actions
Web API Functions
Web API Complex and Enumeration types
Use the Dataverse Web API
OData Version 4.0. Part 3: Common Schema Definition Language (CSDL) Plus Errata 03 7.1 Element edm:NavigationProperty
Submit and view feedback for