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.

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.

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.

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.

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.

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.

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.

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.

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.

Create or edit mapping between fields

1. Click or tap Settings > Customizations.

2. In the Customization area, click Customize the System.

3. Under Components, expand Entities, and then expand the entity you want.

4. Click either 1:N Relationships or N:1 Relationships.

5. In the main pane, in the Type list, select Mappable.

6. Select a mappable relationship. Then, on the Actions toolbar, click Actions, and then click Edit.

7. Under Related, click Mappings.

8. For each new mapping, on the Actions toolbar, click New.

9. In the Create Field Mapping dialog box, select the source field from Source Entity Fields. Select the target field from Target Entity Fields.

10. Click OK.

11. Click Save and Close to close the Relationship form.

12. When your customizations are complete, publish them

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