Entity relationship behavior

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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

  • Automate business processes

  • Cascading behavior

In This Topic

Preserve data integrity

Automate business processes

Cascading behavior

Configure entity relationship behavior

Preserve data integrity

Each entity can have rules that define a valid record. For example, a Microsoft Dynamics 365 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 Microsoft Dynamics 365 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 Microsoft Dynamics 365 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 Microsoft Dynamics 365. 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 Microsoft Dynamics 365 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 Microsoft Dynamics 365 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 TechNet: 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

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

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 class 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 How record-based security can be used to control access to records in Microsoft Dynamics 365, 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.

See Also

One-to-many relationships
Use the Organization service with Dynamics 365 metadata
Customize entity metadata
Customize entity attribute metadata
Customize entity relationship metadata
Customize entity and attribute mappings
Customize labels to support multiple languages
How record-based security can be used to control access to records in Microsoft Dynamics 365
Sample: Create and retrieve entity relationships

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright