Customize entity relationship metadata
Applies to Dynamics 365 for Customer Engagement apps version 9.x
Entity relationships define the ways that entity records can be associated with records of other entities or the same entity. Creating new entity relationships creates new table relationships in the database. Use entity relationships to define specific associations that are frequently used to associate records for reports or in the user interface. Once a relationship exists, you can associate and disassociate records based on the relationship using the
Disassociate methods. More information: Actions on Entity Records
For relationships between individual records that are less formal and more flexible, see Connection Entities.
This topic is about working with entity relationships programmatically. For information about working with entity relationship in the application, see Create and edit entity relationships.
Types of entity relationships
Dynamics 365 for Customer Engagement apps provides two types of entity relationships. Both of these inherit from the RelationshipMetadataBase class:
Before you create a new entity relationship programmatically, check to see whether the entities are eligible to participate in the relationship. There are constraints applied to entity relationships that use the following
CanBeRelatedEntityInRelationship. These restrictions are taken into account when you manually create entity relationships in the customization tools. There are messages that you can use to determine which relationships an entity can use and what other entities are valid for that type of relationship. More information: Entity Relationship Eligibility
Both types of entity relationships allow for options to display navigation links between related records. More information: Configuring Associated Menus
In a one-to-many entity relationship, many referencing (related) entity records can be associated with a single referenced (primary) entity record. The referenced entity record is sometimes referred to as the ”parent” and records of the referencing entity are referred to as ”children.”
In an entity node on a solution page, this kind of entity relationship is displayed as either a 1-to-Many (1:N) Relationship or a Many-to-1 (N:1) Relationship. These terms are used because you navigate to entity relationships through one of the entities. The label reflects which role the current entity has in the relationship.
See Web API: Create a one-to-many relationship for information on how to use the Web API for creating a 1:N relationship.
For Organization Service, you use an instance of the OneToManyRelationshipMetadata class when you work with this kind of entity relationship. Each entity relationship has a unique schema name that you use to retrieve it. For more information, see SchemaName. Each entity relationship of this kind also has a referenced entity (Primary Entity) with a referenced attribute, and a referencing entity (Related Entity) with a referencing attribute. The referencing attribute can be displayed as a lookup field in an entity form. For more information, see
|Web API||SDK Assembly|
You may require that a referencing entity have a reference by setting the
AttributeRequiredLevel enumeration (AttributeRequiredLevel EnumType or AttributeRequiredLevel enumeration) to
ApplicationRequired on the referencing attribute. To maintain data integrity, when you do this you should also specify what you want to occur if the primary record is deleted. Use the
OneToManyRelationshipMetadata.CascadeConfiguration property to either prevent deleting the primary record or automatically delete the related record as well to prevent an orphaned record.
You can also use cascading configuration to automate behavior when specific actions are taken on related records in the organization. More information: Entity Relationship Behavior
Map data to new records
When there is a one-to-many entity relationship, you can specify that data from certain fields in the referenced entity can be transferred to any new related records created in the context of the relationship. This can streamline data entry when you are creating new related records. For more information, see Entity and Attribute Mappings.
Self-referencing one-to-many entity relationships
A self-referencing relationship is where the referencing and referenced entity is the same. For example, the account entity has a self-referencing one-to-many relationship that allows for a lookup labeled Parent Account. If the entity relationship behavior is defined as Parental it is not possible for a record to reference itself because this would create a circular reference when cascading behaviors are applied. More information: Entity Relationship Behavior
Hierarchical one-to-many entity relationships
With Dynamics 365 for Customer Engagement apps, you can specify one self-referencing one-to-many entity relationship as the designated hierarchical relationship for an entity. The
OneToManyRelationship.IsHierarchical property (Microsoft.Dynamics.CRM.OneToManyRelationship.IsHierarchical or OneToManyRelationshipMetadata.IsHierarchical) flags this relationship as the one-to-many relationship to use for the entity.
All one-to-many entity relationships represent a type of hierarchy, but relationships explicitly flagged using the
IsHierarchical property are the only entity relationships that support the hierarchy visualizations in the application as well as new query operators to retrieve hierarchically related records. More information: Query hierarchical data
Change the name of Web API navigation properties
If you want to apply a custom Web API navigation property name for a one-to-many relationship you can set values for the
In a many-to-many entity relationship many entity records can be associated with many other entity records. Unlike one-to-many relationships, there is no lookup field on either entity and therefore no intended hierarchy. Records related using a many-to-many relationship can be considered peers and the relationship is reciprocal. A many-to-many relationship may also be self-referential. Because there is no cascading behavior involved in many-to-many relationships, you can allow an individual record to have a reference to itself.
See Create a Many-to-Many relationship using the Web API for information on how to use the Web API for creating a N:N relationship.
You use an instance of the
ManyToManyRelationshipMetadata (ManyToManyRelationshipMetadata EntityType or ManyToManyRelationshipMetadata class) when you work with this kind of entity relationship. Each entity relationship has a unique
RelationshipMetadataBase.SchemaName that you use to retrieve it.
Creating a many-to-many entity relationship creates a new intersect entity where the
EntityMetadata.IsIntersect property is true. Records for this entity track each individual many-to-many relationship. You cannot add custom attributes to intersect entities.
Change the name of Web API navigation properties
If you want to apply a custom Web API navigation property name for a many-to-many relationship you can set values for the ManyToManyRelationshipMetadata EntityType.Entity1NavigationPropertyName and ManyToManyRelationshipMetadata EntityType.Entity2NavigationPropertyName properties.
Configure associated menus
Both types of entity relationships allow for configuration of navigation links between related records. Use the
Metadata.AssociatedMenuConfiguration properties in each type of entity relationship definition to specify how you want the navigation links in an entity form to be displayed.
These values provide the default configuration for the relationship. You can use the form editor to override these options for each form. More information: Change navigation within a form
Provides the following options:
Provides the following options:
You cannot add new groups, but you can change the text displayed for them using the form editor.
If you select
AssociatedMenuBehavior.UseLabel, you must provide a custom label.
The integer provided for the order will control the relative position of navigation items in the group. The lower the value, the higher the item appears relative to the values of other items in the group.
Create and update entity relationships using Web API
Extend the Metadata Model for Dynamics 365 for Customer Engagement apps
Entity Relationship Messages
Entity Relationship Eligibility
Entity Relationship Behavior
Create Entity Relationships
Sample: Create Entity Relationships
Sample: Dump Entity Relationship Information to a File
Entity and Attribute Mappings
Retrieve Records for Many-To-Many Relationships using Intersect Entities
Send feedback about: