Customize entity relationship metadata


Applies To: Dynamics CRM 2013

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 Associate and 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.

Microsoft Dynamics CRM provides two types of entity relationships. Both of these inherit from the RelationshipMetadataBase class:

Before you create a new entity relationship, check to see whether the entities are eligible to participate in the relationship. More information: Entity relationship eligibility

Both types of entity relationships allow for options to display navigation links between related records. More information: Configure associated menus

In this kind of entity relationship, many referencing (related) entity records can be associated with a single referenced (primary) entity record. This represents a type of hierarchy. 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.

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 ReferencedEntity, ReferencedAttribute, ReferencingEntity, and ReferencingAttribute.

You may require that a referencing entity have a reference by setting the AttributeRequiredLevel 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 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 business processes in the organization. More information: Entity relationship behavior

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 Customize entity and attribute mappings.

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

In this kind of 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 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.

You use an instance of the ManyToManyRelationshipMetadata class when you work with this kind of entity relationship. Each entity relationship has a unique SchemaName that you use to retrieve it

Creating a many-to-many entity relationship creates a new intersect entity where the IsIntersect property is true. Records for this entity track each individual many-to-many relationship. You cannot add custom attributes to intersect entities.

Both types of entity relationships allow for configuration of navigation links between related records. Use the 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: Customization Guide: Use the form editor: Edit Navigation


Provides the following options:

  • DoNotDisplay

  • UseCollectionName

  • UseLabel


Provides the following options:

  • Details

  • Marketing

  • Sales

  • Service

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.