Create 1:N (one-to-many) relationships between entities
This topic applies to Dynamics 365 Customer Engagement (on-premises). For the Power Apps version of this topic, see: Create and edit One-to-many or Many-to-one entity relationships using Power Apps portal
The easiest way to create a 1:N relationship is to create a new lookup field for an entity. This allows you to set the common field values for the lookup field as well as two additional options when you set the Type to Lookup. Those additional fields are Target Record Type and Relationship Name.
Target Record Type selects the Primary Entity in the 1:N relationship. Relationship Name is auto-generated for you based on the two entities that participate in the relationship. You typically don’t need to edit this, but you can if you want. The name of the entity relationship contains the customization prefix of the solution publisher for the solution you are currently working in.
Note
If you care about the customization prefix, be sure you are working within the context of a solution that is linked to the solution publisher with the prefix you want.
However, when you create a 1:N relationship by creating a lookup field, certain default values are set for you. If you want to edit some of the options available in the relationship, you must locate the relationship and edit it.
Custom 1:N relationships can’t be created for all entities. When this is true there is no option to create a new custom entity relationship using the solution explorer. If you use the metadata browser, you can filter the list of entities according to the CanBePrimaryEntityInRelationship and CanBeRelatedEntityInRelationship properties.
The definition for the 1:N relationship has four parts: Relationship Definition, Lookup Field, Navigation Pane Item for Primary Entity, and Relationship Behavior.
Create or edit 1:N relationships between entities
Open solution explorer.
Under Components, expand Entities, and then expand the entity you want to work with.
Select 1:N Relationships.
To edit a relationship or view the details for a relationship, select the relationship, and on the Actions toolbar, select More Actions, and then select Edit.
- OR -
To add a new relationship, select New 1-to-Many Relationship.
Important
If New 1-to-Many Relationship does not appear on the Actions toolbar, you cannot create a 1:N relationship for that entity.
For a new relationship, in the Relationship Definition section, in the Related Entity list, select the entity to be related.
Note
Specifying the related entity sets a default value for the Name field. If you change the related entity before you save, the value of the Name changes accordingly.
Select whether this will be searchable to not.
In the Lookup Field section, specify a value for the Display Name field.
Important
Specifying the Display Name sets a default value for the Name field. If you change the Display Name of the lookup field before you save, the value in the Name field will not change. As a result, be sure the Name is meaningful before saving.
In the Field Requirement list, choose an option to specify data requirements for the field prior to saving a record.
In the Navigation Pane Item for Primary Entity section, in the Display Option list, choose an option for displaying associated views or a custom label.
In the Relationship Behavior section, in the Type of Behavior list, choose one of the following options:
Parental. In a parental relationship between two tables, any action taken on a record of the parent table is also taken on any child table records that are related to the primary (or parent) table record. For example, the owner of the parent record has inherited access to the child table records and when the parent record is deleted, all of the child records will also be deleted. For 1:N parental relationship between the parent table (P1) and child entity (C1), the owner of P1 record is granted inherited access to C1 child records.
Referential. In a referential relationship between two entities, you can navigate to any related records, but actions taken on one will not affect the other.
Referential, Restrict Delete. In a referential, restrict delete relationship between two entities, you can navigate to any related records. Actions taken on the parent record will not be applied to the child record, but the parent record cannot be deleted while the child record exists. Note that you cannot delete a record when related records exist.
Configurable Cascading. In a configurable cascading relationship between two entities, you select the behavior associated with each of a set of possible actions.
Important
If you set the behaviors for the actions so that they match the behaviors for the actions associated with another Type of Behavior, when you save the relationship, the Type of Behavior is automatically set to the matching type.
More information: Configure entity relationship behavior
Select Save and Close to close the Relationship form.
When your customizations are complete, publish them:
To publish customizations for only the component that you are currently editing, on the Actions toolbar, select Publish.
To publish customizations for all unpublished components at one time, on the nav bar or in the Navigation Pane, select Entities, and then on the Actions toolbar, select Publish All Customizations.
Note
- A custom entity cannot be the primary entity in a relationship with a related system entity that cascades. This means you cannot have a relationship with any action set to Cascade All, Cascade Active, or Cascade User-Owned between a primary custom entity and a related system entity.
- No new relationship can have any action set to Cascade All, Cascade Active, or Cascade User-Owned if the related entity in that relationship already exists as a related entity in another relationship that has any action set to Cascade All, Cascade Active, or Cascade User-Owned. This prevents relationships that create a multi-parent relationship.
- Any time you change user-interface elements or implement form scripts for an entity, you need to publish changes to apply them. Any customizations that change the data schema of an app, such as custom entities, relationships, or fields are applied immediately.
- If a relationship is part of a managed solution, the developer of the managed solution can restrict you from customizing the relationship.
- Installing a solution or publishing customizations can interfere with normal system operation. We recommend that you schedule a solution import when it’s least disruptive to users.
Relationship definition
Depending on whether you chose to create a New 1-to-Many Relationship or a New Many-to-1 Relationship from the solution explorer, either the Primary Entity or Related Entity fields will be pre-populated. You only need to choose the other one. A default value for the Name field is pre-populated based on the solution publisher’s customization prefix and the names of the entities you choose to participate in the relationship. You can edit this if you want. If you create more than one custom relationship between two entities and use the same customization prefix for both, the auto-generated name value will not be unique and you will not be able to save the new relationship. You must edit the name to differentiate it from any existing name before you can save it. Once saved, you cannot change it.
If you don’t want to have this entity relationship visible in Advanced Find, set the Searchable value to No.
Lookup fields
These fields are the common properties all fields have except Searchable, Field Security, and Auditing. To edit these values for the lookup field that is created with the entity relationship, you must locate and edit the lookup field separately after you create the entity relationship. More information: Create and edit fields.
As a general rule, the Display Name should correspond to the primary entity display name.
Navigation pane item for primary entity
The primary entity can reveal lists of related entities if you expand the navigation pane. The options in this group control how or whether to display this list. These navigation items can also be edited using the form editor and, by using JavaScript, a developer can apply changes to these items when the form is displayed.
| Field | Description |
|---|---|
| Display Option | - Do Not Display: Choose this if you do not want to allow people to be able to navigate to a list of related entity records. - Use Custom Label: Choose this if you want to specify a custom label to use. - Use Plural Name: Choose this if you want to use the plural name of the related entity as the label. |
| Custom Label | When you select Use Custom Label as the display option, enter the custom label you want to use instead of the related entity plural name. |
| Display Area | - Details: Choose this to include the navigation item in the Common group. - Marketing: Choose this to include the navigation item in the Marketing group. - Sales: Choose this to include the navigation item in the Sales group. - Service: Choose this to include the navigation item in the Service group. |
| Display Order | This number controls where the navigation item will be included within the selected display area. The range of allowed numbers begins with 10,000. Navigation pane items with a lower value appear above other relationships with a higher value. |
Relationship behavior
In a 1:N relationship, you can control how the relationship behaves to support business rules for your organization. Why would you want to do this? Let’s look at an example.
Let’s say that you have a new salesperson and you want to assign them a number of existing opportunities currently assigned to another salesperson. Each opportunity record may have a number of task activities associated with it. You can easily locate the active opportunities you want to reassign and assign them to the new salesperson. But what should happen for any of the task activities that are associated with the opportunities? Do you want to open each task and decide whether they should also be assigned to the new salesperson? Probably not. Instead, you can let the relationship apply some standard rules for you automatically. These rules only apply to task records associated to the opportunities you are reassigning. The entity relationship is named Opportunity_Tasks. Your options are:
Reassign all active tasks.
Reassign all tasks. This is the default behavior.
Reassign none of the tasks.
Reassign all tasks currently assigned to the former owner of the opportunity.
The relationship can control how actions performed on a record for the primary entity record cascade down to any related entity records. The actions and possible behaviors are shown in the following table.
| Action | Description | Possible behaviors |
|---|---|---|
| Assign | What should happen when the primary entity record changes ownership? | - Cascade Active - Cascade All - Cascade None - Cascade User Owned |
| Share | What should happen when the primary entity record is shared? | - Cascade Active - Cascade All - Cascade None - Cascade User Owned |
| Unshare | What should happen when sharing of the primary entity record stops? | - Cascade Active - Cascade All - Cascade None - Cascade User Owned |
| Reparent | What should happen when a lookup field value for a parental type relationship in the primary entity record is changed? A parental type relationship is one that uses Cascade All for all actions. - Cascade Active - Cascade All - Cascade None - Cascade User Owned |
|
| Delete | What should happen when the primary entity record is deleted? | - Cascade All - Remove Link - Restrict Delete |
| Merge | What should happen when the primary entity record is merged with another record? | - Cascade All - Cascade None |
Each of these actions can be configured to control how actions cascade down to records related to the primary entity record through the 1:N entity relationship. The behavior options are in the following table.
| Behavior | Description |
|---|---|
| Cascade Active | Perform the action on all active related entity records. |
| Cascade All | Perform the action on all related entity records. |
| Cascade None | Do nothing. |
| Remove Link | Remove the value of the lookup field for all related entity records. |
| Restrict Delete | Prevent the primary entity record from being deleted when related records exist. |
| Cascade User Owned | Perform the action on all related entity records owned by the same user as the primary entity record. |
How these actions are applied within a relationship can be categorized or applied using the Type of Behavior field values described in the following table.
| Field value | Description |
|---|---|
| Parental | All actions use the Cascade All behavior. |
| Referential | Assign, Share, Unshare, and Reparent use the Cascade None behavior. Delete uses the Remove Link behavior. Merge uses the Cascade All behavior. |
| Referential, Restrict Delete | The same as Referential, except that Delete uses the Restrict Delete behavior. |
| Configurable Cascading | Individual behaviors can be assigned for each action. If the choices match any of the other Type of Behavior categories, the value will change to that Type of Behavior value. |
Limitations on behaviors you can set
There are some limitations you should keep in mind when you define entity relationships.
A custom entity can’t be the primary entity in a relationship with a related system entity that cascades. This means you can’t have a relationship with any action set to Cascade All, Cascade Active, or Cascade User-Owned between a primary custom entity and a related system entity.
No new relationship can have any action set to Cascade All, Cascade Active, or Cascade User-Owned if the related entity in that relationship already exists as a related entity in another relationship that has any action set to Cascade All, Cascade Active, or Cascade User-Owned. This prevents relationships that create a multi-parent relationship.
Cascading on merge can't be set or changed, and is dependent on the referenced entity. If the referenced entity is an account, contact, or lead, the action cascades. Otherwise, it does not.