Customize entity and attribute mappings


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

You can map attributes between entities that have an entity relationship. This lets you set default values for a record that is created in the context of another record. Use the customization tools in the application to map attributes. See TechNet: Customize your CRM system topic TechNet: Create and edit entity relationships : Mapping Entity Fields. See the section on Mapping entity fields for more information.

See TechNet: Entity and attribute mappings for a table that shows the default system entity and field mappings.

In This Topic

Behavior in the application

Using entity and attribute mapping data

Auto-mapping attributes between entities

Retrieve the entity and attribute mappings

Behavior in the application

Mapping in Microsoft Dynamics 365 streamlines data entry when you create new records that are associated with another record. When an entity has an entity relationship with another entity, you can create new related entity records by using the Create Related tab in the ribbon. When you create a new record in this manner, mapped data from the primary entity record is copied to the form for the new related entity record. By mapping entity attributes, you control what data is copied by adding new mappings in the relationship between the two entities. If you create a record in any way other than from the associated view of the primary entity, data is not mapped.

For example, you might want to set up a mapping between the address fields in accounts and the address fields in contacts. With this mapping, when a user adds a contact associated with a specific account, the address fields for the contact are populated automatically.

You can map one attribute to multiple target attributes. For example, you can map address information in an account to both the billing and shipping addresses in an order.

Mapping is applied before a new, related record is created. Users can make changes before saving the record. Later changes to the data in the primary record are not applied to the related record.

Using entity and attribute mapping data

When creating new records in the context of an existing record where a mapping exists between the entities, you can use the InitializeFromRequest message to define a new record that contains the values specified in the mapping. You can then use the IOrganizationService.Create method to save the record. In in this manner, any mappings that you define are applied.

Valid entity maps are created when an entity relationship is created. Use the entity_map_attribute_maps entity relationship to retrieve the attribute maps for the pair of entities specified by the entity map.

You can create or update attribute map records. The following requirements must be met for attribute maps:

  • The AttributeMetadata type must match.

  • The length of the target field cannot be shorter than the source field.

  • The format must match.

  • The target field must not be used in another mapping.

  • The source field must be visible on the entity form.

  • The target field must be a field in which a user can enter data.

  • Address ID values cannot be mapped.

  • PartyList attributes, where AttributeMetadata.AttributeType is AttributeTypeCode.PartyList cannot be mapped.

Auto-mapping attributes between entities

You can edit attribute mappings between entities for entity relationships that support mapping.

In addition to creating each attribute map manually, you can use the AutoMapEntityRequest message to generate a new set of attribute mappings. This message performs the action found under the Generate Mappings menu option in the More Actions menu on the toolbar. This message maps all the attributes between the two related entities where the attribute names and types are identical. This message is provided as a productivity enhancement so that you do not have to manually add all attribute mappings. Instead, you can generate a set of likely mappings and minimize the amount of manual work to add or remove individual mappings to meet your requirements.


Automatically generating mappings in this manner will remove any previously defined attribute mappings and may include mappings that you do not want.

Retrieve the entity and attribute mappings

An easy way to see the mappings that have been created is to use the following FetchXML query. For more information on how to run this query, see Use FetchXML to construct a query.

<fetch version='1.0' mapping='logical' distinct='false'>
   <entity name='entitymap'>
      <attribute name='sourceentityname'/>
      <attribute name='targetentityname'/>
      <link-entity name='attributemap' alias='attributemap' to='entitymapid' from='entitymapid' link-type='inner'>
         <attribute name='sourceattributename'/>
         <attribute name='targetattributename'/>

See Also

Use the Organization service with Dynamics 365 metadata
EntityMap entity messages and methods
AttributeMap entity messages and methods
TechNet: Create and edit entity relationships: Mapping Entity Fields

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright