Customize entity relationship metadata

 

Applies To: Dynamics CRM 2015

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.

In This Topic

Types of entity relationships

One-to-many relationships

Many-to-many relationships

Configure associated menus

Types of entity relationships

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

• One-to-many relationships

• Many-to-many relationships

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 EntityMetadata properties: CanBeInManyToMany, CanBePrimaryEntityInRelationship, and 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: Configure associated menus

One-to-many relationships

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.

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 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 Customize 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 Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update, you can specify one self-referencing one-to-many entity relationship as the designated hierarchical relationship for an entity. The OneToManyRelationshipMetadata.IsHierarchical property 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

Many-to-many relationships

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.

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.

Configure associated menus

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: TechNet: Use the form editor: Edit Navigation

• Behavior
  Provides the following options:

  • DoNotDisplay

  • UseCollectionName

  • UseLabel

• Group
  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.

• Label
  If you select AssociatedMenuBehavior.UseLabel, you must provide a custom label.

• Order
  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.

See Also

Extend the metadata model
Entity relationship metadata messages
Entity relationship eligibility
Entity relationship behavior
Create and retrieve entity relationships
Sample: Create and retrieve entity relationships
Sample: Dump entity relationship information to a file
Customize entity and attribute mappings
Retrieve records for many-to-many relationships using intersect entities

© 2016 Microsoft. All rights reserved. Copyright