Entity relationship behavior

Article
08/11/2022

When a one-to-many entity relationship exists there are cascading behaviors that can be configured to preserve data integrity and automate business processes. This topic will explain some key concepts and describe how you can configure these cascading behaviors.

Before describing how to configure entity relationship behaviors it is useful to consider how it applies to your business. Three key concepts are:

Preserve data integrity

Each entity can have rules that define a valid record. For example, a Dynamics 365 Customer Engagement (on-premises) opportunity record must include a reference to a potential customer. Users can’t create a new opportunity record without either adding an existing customer or creating a new customer record.

But what if the account or contact that represents the customer is deleted? In a case like this, possible alternatives are to either:

Restrict any attempt to delete a customer record with an associated opportunity.
Cascade the delete action when a corresponding customer record is deleted so that any related opportunity records are automatically deleted.

In Dynamics 365 Customer Engagement (on-premises) for the one-to-many relationships that relate opportunities with customers, such as Opportunity.opportunity_customer_accounts and Contact.opportunity_customer_contacts, the behavior is to cascade the delete action.

When you model your data to use in Dynamics 365 Customer Engagement (on-premises) you will have similar decisions for how you want to preserve data integrity.

Automate business processes

Your business processes may require you to perform actions on records that have related records. For example, you may need to assign an account to a new salesperson. If that account record has any opportunity records, some options include:

Do nothing. The opportunities should continue to be owned by the individuals who work on them.
Assign all the opportunities to the new salesperson. As the new owner of this account record, the salesperson is now responsible for all opportunities related to that account.
Only assign the active opportunities to the new salesperson. Preserve the owner for any inactive opportunity records for reporting purposes.
Only assign the opportunities owned by the previous account owner to the new salesperson. This allows the new salesperson to replace the previous owner.

These options are common ones you can configure using entity relationship behavior in Dynamics 365 Customer Engagement (on-premises). If you require different behaviors consider purchasing a solution containing the behavior you need or developing a plugin to provide additional options.

Cascading behavior

These configuration options are called cascading behaviors because they cascade down the hierarchy of related entities. For example, if deleting an account causes related opportunities to be deleted, what about the activities associated with the opportunities? In Dynamics 365 Customer Engagement (on-premises) the behavior defined in each of the entity relationships for activity type entities is that they are deleted as well.

However, not all entities are treated this way. For example, orders and invoices contain important business data that shouldn’t be inadvertently deleted. They have entity relationship behavior configured to restrict deleting customer or opportunity records that they are associated with. Before you can delete the customer or opportunity that has a related order or invoice record, you must delete the order or invoice first.

As you model your business data by creating custom entities or when using existing Dynamics 365 Customer Engagement (on-premises) system entities, consider the behavior you require and the implications for the entire hierarchy of related entities.

Parental entity relationships

Each pair of entities that are eligible to have a 1:N relationship can have multiple 1:N relationships between them. Yet only one of those relationships can be considered a parental entity relationship. See Customizable parental entity relationships for a list of all the customizable parental entity relationships.

A parental entity relationship is any 1:N entity relationship where one of the cascading options (defined in CascadeType) in the Parental column of the following table is true.

Action	Parental	Not Parental
Delete	Cascade	RemoveLink Restrict
Share	Cascade UserOwned Active	NoCascade
Unshare	Cascade UserOwned Active	NoCascade
Assign	Cascade UserOwned Active	NoCascade
Reparent	Cascade UserOwned Active	NoCascade

Each referencing entity in a 1:N entity relationship has one referencing attribute where the relationship can be considered parental.

For example, if you create a new custom entity and add a 1:N entity relationship with the account entity where your custom entity is the referencing entity, you can configure the actions for that entity relationship to use the options in the Parental column. If you later add another 1:N entity relationship with your custom entity as the referencing entity you can only configure the actions to use the options in the Not Parental column.

Usually this means that for each entity pair there is only one parental relationship. There are some cases where the referencing attribute on the referencing may include a reference to more than one type of entity.

For example, the Opportunity entity has a referencing attribute called customerid where a reference to either a contact or account record may be stored. There are two separate parental 1:N entity relationships in this case.

Any activity entity, for example, a task, fax, phone call, and so on, has a similar set of parental entity relationships for entities that can be associated using the regardingobjectid referencing attribute.

Configure entity relationship behavior

Using Web API

When working with Web API, you can define a One-to-Many relationship using OneToManyRelationshipMetadata EntityType. This definition includes the name of the intersect entity to be created as well as how the relationship should be displayed in the application by using AssociatedMenuConfiguration ComplexType, Label ComplexType and LocalizedLabel ComplexType. More information: Create a One-to-Many relationship.

Using Organization Service

When you use CreateOneToManyRequest or UpdateRelationshipRequest you include an instance of a OneToManyRelationshipMetadata class in the body of the request. In the CascadeConfiguration property of that class you use the CascadeConfiguration class.

The CascadeConfiguration (CascadeConfiguration class or CascadeConfiguration ComplexType) contains the properties representing actions that may be performed on the referenced entity in the one-to-many entity relationship. Each property can be assigned one of the values of the CascadeType EnumType.

Value	Application label	Description
Active	Cascade Active	Perform the action on all active referencing entity records associated with the referenced entity record.
Cascade	Cascade All	Perform the action on all referencing entity records associated with the referenced entity record.
NoCascade	Cascade None	Do nothing.
RemoveLink	Remove Link	Remove the value of the referencing attribute for all referencing entity records associated with the referenced entity record.
Restrict	Restrict	Prevent the Referenced entity record from being deleted when referencing entities exist.
UserOwned	Cascade User Owned	Perform the action on all referencing entity records owned by the same user as the referenced entity record.

The CascadeConfiguration (CascadeConfiguration class or CascadeConfiguration ComplexType) contains the following properties representing actions that may be performed on the referenced entity in the one-to-many entity relationship.

Action	Description	Valid options
Assign	The referenced entity record owner is changed.	Active Cascade NoCascade UserOwned
Delete	The referenced entity record is deleted. Note: The options for this action are limited.	Cascade RemoveLink Restrict
Merge	The record is merged with another record. Note: For referenced entities that can be merged, Cascade is the only valid option. In other cases use NoCascade.	Cascade NoCascade
Reparent	See About the Reparent action below.	Active Cascade NoCascade UserOwned
Share	When the referenced entity record is shared with another user.	Active Cascade NoCascade UserOwned
Unshare	When sharing is removed for the referenced entity record.	Active Cascade NoCascade UserOwned

About the reparent action

The reparent action is very similar to the share action except that it deals with the inherited read access rights instead of explicit read access rights.

Note

For more information about inherited access rights, see Use record-based security to control access to records, especially the Sharing and Inheritance section.

The reparent action is when you change the value of the referencing attribute in a parental relationship. When a reparent action occurs, the desired scope of the inherited read access rights for related entities might change. The cascade actions related to the reparent action refer to changes to read access rights for the entity record and any entity records related to it. For more information about how an entity relationship is configured to be parental, see Parental Entity Relationships.

For example, there is a parental relationship between Opportunity and Account based on the CustomerId referencing attribute. If you are the owner of an account and there is an opportunity associated with that account, you inherit read access rights to that opportunity and any records associated with it. If the CustomerId referencing attribute value for the opportunity is changed to refer to a different account, the owner of that account inherits read access rights to the opportunity if the Reparent action is Cascade. You can disable this automatic inheritance of read access rights if you set the reparent action to NoCascade. You can use the Active or UserOwned options to specify filters on which records are affected by the change in access rights. For any records related to the opportunity using a parental relationship, the reparent action cascades down those entity relationships and read access rights are inherited based on the filters set for the Reparent action.