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