Create and edit entity relationships
Applies To: Dynamics CRM 2013
Entity relationships define how records can be related to each other in the database. At the simplest level, adding a lookup field to an entity creates a new 1:N (One-to-Many) relationship between the two entities and allows you to place that lookup field in a form. With the lookup field, users can associate multiple “child” records of that entity to a single “parent” entity record.
Beyond simply defining how records can be related to other records, 1:N entity relationships also provide data to address the following questions:
When I delete a record should any records related to that record also be deleted?
When I assign a record, do I also need to assign all records related to that record to the new owner?
How can I streamline the data entry process when I create a new related record in the context of an existing record?
How should people viewing a record be able to view the associated records?
Entities can also participate in a N:N (Many-to-Many) relationship where any number of records for two entities can be associated with each other.
In This Topic
Evaluate whether to use entity relationships or connections.
Types of entity relationship
Creating and editing 1:N relationships
Mapping entity fields
Creating and editing N:N (Many-to-Many) relationships
Setting managed properties for relationships
Evaluate whether to use entity relationships or connections.
Entity relationships are metadata that make changes to the database. These relationships allow for queries to retrieve related data very efficiently. Use entity relationships to define formal relationships that define the entity or that most records can use. For example, an opportunity without a potential customer wouldn’t be very useful. The Opportunity entity also has a N:N relationship with the Competitor entity. This allows for multiple competitors to be added to the opportunity. You may want to capture this data and create a report that shows the competitors.
There are other less formal kinds of relationships between records that are called connections. For example, it may be useful to know if two contacts are married, or perhaps they are friends outside of work, or perhaps a contact used to work for another account. Most business won’t generate reports using this kind of information or require that it is entered, so it’s probably not worthwhile to create entity relationships.
Types of entity relationship
When you look at the solution explorer you might think that there are three types of entity relationships. Actually there are only two as shown in the following table.
Relationship Type |
Description |
|---|---|
1:N (One-to-Many) |
An entity relationship where one entity record for the Primary Entity can be associated to many other Related Entity records because of a lookup field on the related entity. When viewing a primary entity record you can see a list of the related entity records that are associated with it. |
N:N (Many-to-Many) |
An entity relationship that depends on a special Relationship Entity, sometimes called an intersect entity, so that many records of one entity can be related to many records of another entity. When viewing records of either entity in a N:N relationship you can see a list of any records of the other entity that are related to it. |
The N:1 (Many-to-one) relationship type exists in the solution explorer user interface because the solution explorer shows you a view grouped by entities. 1:N relationships actually exist between entities and refer to each entity as either a Primary Entity or Related Entity. The related entity, sometimes called the child entity, has a lookup field that allows storing a reference to a record from the primary entity, sometimes called the parent entity. A N:1 relationship is just a 1:N relationship viewed from the related entity.
Creating and editing 1:N relationships
The easiest way to create a 1:N relationship is to create a new lookup field for an entity. This allows you to simply 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 even 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.
For step-by-step instructions, see Create or edit N:1 relationships between entities
Custom 1:N relationships can’t be created for all entities. When this is true there will simply be 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. See 88b18946-474c-4c94-8e4c-27532f930757#BKMK_MetadataBrowser for more information.
The definition for the 1:N relationship has four parts: Relationship Definition, Lookup Field, Navigation Pane Item for Primary Entity, Relationship Behavior.
.jpeg "1:N Entity Relationship")
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 wish. 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 Field
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: d88677fa-2caf-47b0-aec6-10a25a7ec9c3#BKMK_CreatingAndEditngFields
As a rule of thumb, the Display Name should correspond to the primary entity display name.
Navigation pane item for primary entity
The primary entity can display lists of related entities by expanding 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 |
|
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 |
|
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 re-assign 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 re-assigning. The entity relationship is named Opportunity_Tasks. Your options are:
Re-assign all active tasks.
Re-assign all tasks. This is the default behavior.
Re-assign none of the tasks.
Re-assign 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? |
|
Share |
What should happen when the primary entity record is shared? |
|
Unshare |
What should happen when sharing of the primary entity record stops? |
|
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. Customizable parental entity relationships lists the customizable parental system relationships. |
|
Delete |
What should happen when the primary entity record is deleted? |
|
Merge |
What should happen when the primary entity record is merged with another record? |
|
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. Customizable parental entity relationships lists all of the customizable system entity relationships that use the parental 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 that 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 avoids relationships that create a multi-parent relationship.
Mapping entity fields
Let’s say that you want to add a new contact record for a person who is an employee for a specific account. You can do this in two different ways.
You could just navigate to Sales > Contacts and create a new contact record from scratch. But then you need to set the parent account and enter several items of information (such as address and phone information) which is probably the same as the parent account. This can be time consuming and introduces opportunities for errors.
The easier way is to start with the account entity and, using the Contacts subgrid on the form, simply click the (+) to add a contact. It will first guide you to look up any existing related contacts so you don’t accidentally create a duplicate record. If you don’t find an existing record, you can just click New and create a new contact record. The difference is that certain items of data from the account record will be copied into the new contact form to set certain default values which you can edit before saving. This can save a lot of time when you are entering data and help reduce errors.
Entity and attribute mappings shows all the default mappings set for Microsoft Dynamics CRM 2013.
Note
These mappings aren’t applied to related records created using a workflow or dialog process. They aren’t automatically applied to new records created using code, although developers can use a special message called InitializeFromRequest to create a new record using available mappings.
These mappings only set default values to a record before it is saved. People can edit the values before saving. The data that is transferred is the data at that point in time. It isn’t synchronized. If the information in the primary entity record changes, the related entity record data that was transferred when it was created won’t change.
The default values set when you create a new record from a list aren’t actually defined within the entity relationships, but they are exposed in the relationship user interface. Not every 1:N entity relationship has them. When you view a list of 1:N (or N:1) entity relationships for an entity, you can filter the relationships shown by type. You can select either All, Custom, Customizable, or Mappable. Mappable entity relationships provides access to allow mapping entity fields.
The following rules show what kinds of data can be mapped.
Both fields must be of the same type and the same format.
The length of the target field must be equal to or greater than the length of the source field.
The target field can’t be mapped to another field already.
The source field must be visible on the form.
The target field must be a field that a user can enter data into.
If the fields are option sets, the integer values for each option should be identical.
Address ID values can’t be mapped.
Note
If you need to map option set fields, we recommend you configure both fields to use the same global option set. Otherwise, it can be difficult to keep two separate sets of options synchronized manually. If the integer values for each option aren’t mapped correctly you can introduce problems in your data. More information: Create and edit global option sets
Create or edit mapping between fields
Click or tap Settings > Customizations.
In the Customization area, click Customize the System.
Under Components, expand Entities, and then expand the entity you want.
Click either 1:N Relationships or N:1 Relationships.
In the main pane, in the Type list, select Mappable.
Select a mappable relationship. Then, on the Actions toolbar, click Actions, and then click Edit.
Under Related, click Mappings.
For each new mapping, on the Actions toolbar, click New.
In the Create Field Mapping dialog box, select the source field from Source Entity Fields. Select the target field from Target Entity Fields.
Click OK.
Click Save and Close to close the Relationship form.
When your customizations are complete, publish them
Note
-
After publishing customizations, these mappings are available for all users. If you reset Internet Information Services (IIS) before you publish customizations, these mappings are available for all users, even though other customizations won’t be available.
-
If you map to or from a field that isn’t displayed on a form, the mapping won't be done until the field is added to a form.
Automatically generate field mappings
You can also generate mappings automatically but you should apply some care when doing this with system entities. Use this when you create custom entities and want to leverage mapping. When viewing the list of mappings, in the More Actions menu select Generate Mappings. This removes any existing mappings and replaces them with suggested mappings that are based only on the fields that have similar names and data types. If you use this on a system entity, you could lose some expected mappings. For custom entities, it helps save time because you can more easily delete any mappings you don’t want and add any others that the generate mappings action didn’t create.
Creating and editing N:N (Many-to-Many) relationships
1:N entity relationships establish a hierarchy between records. With N:N (Many-to-Many) relationships there is no explicit hierarchy. There are no lookup fields or behaviors to configure. Records created using a N:N relationships can be considered peers and the relationship is reciprocal.
With N:N relationships a special entity is created called a Relationship (or Intersect) entity. This entity has a relationship with each of the related entities and only stores the necessary id values necessary to define the relationship. You can’t add custom fields to a relationship entity.
The procedure to create a N:N relationship is essentially choosing the two entities that you want to participate in the relationship and then for each entity define how you want the respective lists to be available within the navigation pane of the form for each entity. These are the same options used for the primary entity in 1:N entity relationships. More information: Navigation pane item for primary entity
For step-by-step instructions, see Create or edit N-N relationships between entities.
Not all entities can be used with N:N relationships. If the New Many-to-Many Relationship button isn’t present, you can’t create a new N:N relationship with this entity. If you use the metadata browser, you can filter on entities that have the CanBeInManyToMany value set to true. More information: 88b18946-474c-4c94-8e4c-27532f930757#BKMK_MetadataBrowser
Setting managed properties for relationships
ece68f5f-ad40-4bfa-975a-3e5bafb854aa#BKMK_ManagedProperties only apply when you include a field with a managed solution and import it into another organization. These settings allow a solution developer to have some control over the level of customization that they want to allow people who install their managed solution to have when they customize an entity relationship. To set managed properties for a relationship, click the Managed Properties button on the menu bar.
With relationships the only managed property is Can Be Customized. This single setting controls all changes that can be made to the entity relationship.
See Also
Create and edit metadata
Create and edit entities
Create and edit fields
Create and edit global option sets
Customizable parental entity relationships
Entity and attribute mappings
© 2016 Microsoft Corporation. All rights reserved. Copyright