Configure entity relationship cascading behavior

Note

Effective November 2020:

  • Common Data Service has been renamed to Microsoft Dataverse. Learn more
  • Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more

This article will be updated soon to reflect the latest terminology.

You can configure cascading behaviors for a one-to-many entity relationship to preserve data integrity and automate business processes. Both Web API and organization service support configuring cascading behavior.

Using Web API to configure cascading behavior

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 Web API.

Using Organization Service to configure cascading behavior

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 later. 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

Note

Assign, Delete, Merge, and Reparent actions will not execute in the following situations:

  • If the original parent record and requested action contain the same values. Example: Attempting to trigger an Assign and choosing a contact that is already the owner of the record
  • Attempting to perform an action on a parent record that is already running a cascading action

Note

When executing an assign, any workflows or business rules that are currently active on the records will automatically be deactivated when the reassignment occurs. The new owner of the record will need to reactivate the workflow or business rule if they want to continue using it.

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

About the merge action

The merge action can sometimes have problems completing if a record that is part of the operation set is deleted while the merge system job is running. Often this will result in an error indicating that the record will be "differently parented" or the child record "might lose its parenting". If this occurs, and you would prefer the merge continue forward even if the record is missing, you can choose to disable the parent check when you select the columns to merge.

Note

When performing a merge between two custom entities, DateTime values will not merge. The DateTime of the target record will remain unchanged.

See also

Entity relationship metadata

Note

Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).