Settings

Entity customizations

Part 5 of "11 things to know about customization"

Published: January 1, 2008

Microsoft Dynamics CRM uses the word “entity” to refer to the structures used to store and manage data. Conceptually, entities are often compared to a table in a database because entities correspond to the types of records Microsoft Dynamics CRM manages. However, entities include much more than a database table. An entity includes definitions of the forms, views, and behavior of Microsoft Dynamics CRM related to a specific record type.

In addition to the default system entities, you can create custom entities. For example, a realtor might add a new entity called Property to store all the houses for sale.

On This Page
Attributes Attributes
Entity relationships Entity relationships

Attributes

Each field in an entity form represents an attribute of the entity. You can add custom attributes to system entities to supplement the system attributes that are provided. For most of the system entities, there are more attributes than fields that you see on the form. Before you create a new attribute, check whether there is already an existing system attribute that fits your needs which you can use instead of creating a new custom attribute.

Access the Attribute Customization page

  1. In the Navigation Pane, click Settings, click Customization, and then click Customize Entities.

  2. Double-click the entity you want to customize.

  3. Under Details, click Attributes.

  4. Double-click the attribute you want to customize, or click New to create a new attribute.

When you create a new custom entity, you must add any additional attributes that you need. The following table shows the types of attributes you can add or modify.

Name Description

nvarchar

This kind of field stores text. You can apply some formatting options, such as Text or Ticker Symbol, to control how the text appears and behaves. You can also specify the maximum length, up to 4000, for the attribute.

picklist

This specifies an HTML select control, often called a drop-down list or combo-box. You define the options that will be displayed in the list.

You can also define the integer values that correspond to the text values for each option. The integer value is what is actually stored in the database for this attribute.

bit

This specifies a field that stores a value of 0 or 1. In the form, you can decide whether to show this attribute as radio buttons, a check box, or a picklist. You can also set the text to display for each value such as True and False, Yes and No, or Always and Never.

int

This field stores an integer, which is a positive or negative number without a decimal point. You must specify the format of the field, and any minimum and maximum values. The minimum value is -2,147,483,648 and the maximum value is 2,147,483,647.

float

This specifies a positive or negative number that uses a decimal. You can set the number of decimal places to display (known as precision), and any minimum and maximum values. The minium value is -1,000,000,000 and the maximum value is 1,000,000,000. The float attribute supports up to 5 decimal places.

money

The money attribute supports multicurrency transactions. You can set the number of decimal places (known as precision) and any minimum and maximum values. The minimum value is -922,337,203,685,477 and the maximum value is 922,337,203,685,477. The money attribute supports up to 4 decimal places.

When you create a money attribute, a corresponding, or base, attribute is also created. The base attribute stores the value of the money attribute in the base currency.

Each entity that has a money attribute must also have a Currency and an Exchange Rate attribute. If these attributes do not already exist they will be created when a new money attribute is added to an entity.

ntext

This specifies a field to store longer text, also known as a text box. These fields store a maximum of 100,000 characters.

datetime

When these fields are displayed on a form, they include a field where the date is visible and can be edited. They also include a calendar control to help locate a specific date. You can decide whether to display the date and time or just the date.

Note

Lookup is not on the list of attribute types you can add. New lookup attributes are created when you create entity relationships.

For more information about configuring fields, see Configure fields.

Field constraints

When you add or edit an attribute, you can also set whether the field that represents that attribute will be required for users to enter data. You have the following choices:

  • Business Required. The user must enter data in this field before they can save a record. This field will appear with a red asterisk.

  • Business Recommended. This does not require the user to enter data. The field will appear with a blue "+" symbol.

  • No Constraint. This is the default setting. It is a regular field with no special constraints.

Top of page

Entity relationships

All entities have some entity relationships with some system entities. For example, the Modified By (modifiedby) and Created By (createdby) attributes are lookup attributes required by the entity relationships to the User entity.

When you create a custom entity, you probably want to relate it to one or more other entities. An entity is usually not very useful until you relate it to other types of records. Also, it is helpful if you know about primary keys and foreign keys, but it is not necessary to create an entity relationship in Microsoft Dynamics CRM.

Understanding entity relationships

Every field in a Microsoft Dynamics CRM form has a corresponding entity attribute. In most cases, if you want to create a new field you would start by creating a new entity attribute. Lookup fields are different. While most types of new entity attributes are created in the Attributes area of an entity, lookup attributes are created automatically when you create an entity relationship.

There are two types of entity relationships you can create:

  • Hierarchical Relationships represent an entity relationship where one record stores a unique reference to another record. The lookup field you are adding will let a user set this reference to another record. The record that has the lookup field is often called the child record. The record that is referenced in the lookup field is called the parent record.

    You choose the type of record that will be available in the lookup field when you define an entity relationship. The parent record type is called the primary entity. The child record type is called the related entity.

    You must start from one of these entities so choose from the following options when you create a hierarchical relationship:

    • 1:N (1-to-Many) Relationships represent hierarchical relationships created or viewed from the primary entity. Any one record from the primary entity can be referenced by many records from the related entity.

    • N:1 (Many-to-1) Relationships represent hierarchical relationships created or viewed from the related entity. Many records from the related entity can reference any one record from the primary entity.

      Note

      Despite the fact that there are two separate hierarchical relationship options it is important to remember that either option can be used to achieve the same result. You do not have to go to both entities to create a relationship between them.

  • N:N (Many-to-Many) Relationships are not hierarchical because the records do not store a unique reference to another record. There is no lookup field on the form in an N:N Relationship. Both records are considered peers. They both look like parent records because they display a list of all the other records they are related to in an associated view.

Creating or editing entity relationships

Access entity relationship customization

  1. In the Navigation Pane, click Settings, click Customization, and then click Customize Entities.

  2. Locate either of the entities that you want to create or edit a relationship with and double-click it.

  3. Under Details, select one of the following, depending on the type of relationship you want to create or edit:

    • 1:N Relationships

    • N:1 Relationships

    • N:N Relationships

  4. Double-click an existing relationship to edit it, or create a new relationship.

Cascading behaviors

The hierarchical entity relationships you create affect the integrity of data. For example, if you create a custom entity called "Bank Account" with an entity relationship to the Account entity, any bank account information stored in those records is not useful without a connection to the related account record. What do you want to occur if that account is deactivated, deleted, or reassigned? Cascading behaviors describe the actions that are performed in response to an event like this.

For example, in most cases, you want to do something if the account is deleted, because the related records could become ”orphaned records” if they aren't related to another account. People might be unable to find the record. In many cases, the related record is not important without the primary record. Therefore, you might as well delete it. However, Microsoft Dynamics CRM doesn't make that decision for you. You decide what is right for your business. Without the ability to automate your preference using cascading behaviors you would have to manually make changes to related records.

Part of configuring a hierarchical entity relationship is deciding what type of behaviors you want for specific actions. In some organizations, if an account is re-assigned, you would want all open sales opportunities to be reassigned, too. You can define the appropriate behavior for your organization using the relationship behavior part of the relationship.

An important consideration: When any actions cascade in a hierarchical entity relationship, that relationship is called a parental relationship. When no actions cascade, the relationship is considered a referential relationship.

When you define a hierarchical entity relationship, you can select an action or type of behavior. The types of behavior are as follows:

  • Parental: Any action taken on a record of the parent entity is also taken on any child entity records that are related to the parent entity record. For example, if you delete a record in the parent entity, the related child entity records are also deleted; or if you share a parent entity record, the related records from the child entity are also shared.

  • Referential: You can navigate to any related records and relate them in reports, but actions taken on one will not affect the other.

  • Referential, Restrict Delete: You can navigate to any related records and relate them in reports. Actions taken on the parent record will not be applied to the child record, but the parent record cannot be deleted while the child records exists.

  • Configurable Cascading: Any action taken on a parent entity record can also be applied to any child entity records. You can define the behavior for each type of action. For example, you can set it up so that if you share a record in the parent entity, any related records for the child entity are not automatically shared. But if you delete a parent entity record, any related child entity records are automatically deleted.

The important thing to remember is that configurable cascading gives you more control over exactly which actions will cascade. But as long as one action cascades, the hierarchical entity relationship is considered parental with regard to the limitations for creating hierarchical entity relationships.

Hierarchical entity relationship limitations

There are two limitations to be aware of when you create hierarchical entity relationships:

  • Each entity can only have one parental relationship. You can create any number of N:1 (Many-to-1) relationships but, except for one, the cascading relationship behavior must be referential.

  • You cannot create a relationship to the virtual customer entity. Case, Opportunity, Quote, and other Microsoft Dynamics CRM entities have relationships that can exist for either Contact or Account entities. These two entities represent customers. Together they are also known as a “virtual customer” entity. You can create relationships to Contact or Account separately, but you cannot create a relationship exactly like the ones in some Microsoft Dynamics CRM system entities like Case, Opportunity, or Quote.

Associated views

When you create a hierarchical entity relationship, an associated view can be displayed in the form of the primary entity. N:N (many-to-many) relationships can display an associated view in both entities participating in the entity relationship.

For custom entity relationships, you can control how the associated view is displayed.

  • For hierarchical entity relationships: Use the Navigation Pane Item for Primary Entity area of the Relationship form.

  • For N:N (many-to-many) entity relationships: Configure both the Current Entity and the Other Entity areas of the Relationship form.

In the Display Option field you have three choices:

  • Do Not Display : This means that an associated view for this relationship will not display. Use this if it is not important to see the associated view.

  • Use Custom Label : This enables the Custom Label field where you can enter a label to use for the associated view. If you have more than one entity relationship to the same entity, use a custom label to differentiate them.

  • Use Plural Name : This uses the plural name defined for the related entity.

If you select Use Custom Label or Use Plural Name, you can specify which subarea of the form navigation pane to display the associated view by selecting from the Display Area drop-down list. The default options are:

  • Details

  • Marketing

  • Sales

  • Service

Within each of the navigation pane areas you can control the display order. Set the Display Order field to a value above 10,000. The entity relationship with the lowest value will appear above the others.

Mapping

An entity relationship presents a list of the associated entities. Users can create new instances of the associated entity from this view when they click the New button. It is much easier to create new records in this manner, because some data from the related record is automatically transferred to the new record, streamlining data entry. You can control which fields are populated with data from the related entity by configuring mapping within the relationship.

Note

It is important not to misunderstand mapping. Microsoft Dynamics CRM does this mapping only on the creation of a new record. It does not maintain the data in the relationship after the record is saved. If a value in the related record changes, the mapped data in the other record will stay as it was when the record was created.

Mapping is configured within each entity relationship. After the entity relationship is saved, the Mappings area appears in the navigation pane area of the relationship form.

Click New to create a new mapping. In the Create Attribute Mapping dialog box, select the source attribute from Source Entity Attributes, select the target attribute from Target Entity Attributes, and then click OK.

Note

When you select attributes, consider the following mapping requirements:

  • Both attributes must be of the same type and the same format.

  • The length of the target attribute must be equal to or greater than the length of the source attribute.

  • The target attribute cannot already be mapped to another attribute.

  • The source attribute must be visible on the form.

  • The target attribute must be a field that a user can enter data into.

  • If the attributes are picklists, the integer values for each option should be identical.

  • Address ID values cannot be mapped.

Caution

It is possible to automatically create mappings for the relationship, but this is usually not recommended. This process will map any mappable attributes based only on the datatype and name of the attribute. All existing mappings are removed.

  • In the Relationship form, on the Actions toolbar, click More Actions.

  • Click Generate Mappings.

Related Links

Part 6: Transportable customizations
Configure fields
Did you find the information that you need?
Yes     No 
If not, what information do you need? (optional)

© 2008 Microsoft Corporation. All rights reserved.