Create data maps for import

Applies to Dynamics 365 (online), version 9.x

To import data into Dynamics 365, you must provide the appropriate data maps.

You can download examples of data maps from Microsoft Downloads:

You use data maps to map the data contained in the source file to the Dynamics 365 entity attributes. You must map every column in the source file to an appropriate attribute. The data in the unmapped columns is not imported during the data import operation.

The data map is represented by the import map (data map) entity. You can create a new map by using the CreateRequest message or update an existing map by using the IOrganizationService.Update method. The map has a unique name that is contained in the ImportMap.Name attribute. You can specify the name of the import source for which this data map is created by using the ImportMap.Source attribute.

Column, list value, and lookup mappings

To map a column, a list value, or lookup value in the source file to a Dynamics 365 attribute, use the following mappings:

Column Mapping

Maps a column in a source file to a Dynamics 365 entity attribute. For column mapping, use the column mapping (ColumnMapping) entity. You can use 1:1 (one-to-one) or 1:N (one-to-many) relationships between source and target attributes. For example, you can map account address information to the billing and shipping addresses in an order.

List Value Mapping

Maps a list value in a source file to a Dynamics 365 attribute of the OptionSetValue type. For list value mapping, use the picklist mapping (PicklistMapping) entity.

If a value specified in the source file column is a list value, such as an OptionSetValue, Status, State, and Boolean, you must provide a list value mapping additionally to a column mapping. For example, map the "bill" and "ship" list values in the source file to the bill and ship values of the OptionSetValue type.

Lookup Mapping

Maps a lookup value in a source file to a Dynamics 365 attribute of the EntityReference type. For lookup mapping, use the lookup mapping (LookupMapping) entity.

If the value specified in the source file references an entity, you must provide a lookup mapping for this value. Use the LookupMapping.LookupSourceCode attribute to specify whether to search for the referenced entity inside the source file or inside Dynamics 365. If you are using early bound types, you can use the LookupSourceType enumeration to set the lookup values. To search inside the source file, use the LookupSourceType.Source value. To search inside Dynamics 365, use the LookupSourceType.System value. For a list of the LookupSourceCode values, see the picklist values for this entity. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also browse the reference documentation for entities in the Entity Reference. You can provide multiple lookup mappings. The asynchronous transformation job processes all available mappings. It finds the referenced records and updates the parse table with the record unique identifiers. For more information, see Run Data Import.

Owner mapping

Use owner mapping to map a user specified in the source file to a user in Dynamics 365. For logging information, use the Dynamics 365 user logon name. For owner mapping, use the owner mapping (OwnerMapping) entity.

Notes and attachments

Mapping for notes and attachments is handled differently from other entities. Notes and attachments are used to append additional information to a record in Dynamics 365. Notes are stored as text and attachments are stored as files in the Dynamics 365 database.

To create a note in Dynamics 365, set the Annotation.IsDocument attribute in the annotation (note) entity to false. To create an attachment, set IsDocument to true.

Use the following settings for mapping notes and attachments:

  • Set the ColumnMapping.SourceAttributeName attribute to “true” or “false”. The “true” value indicates an attachment. The “false” value indicates a note.

  • Set the ColumnMapping.TargetAttributeName attribute to IsDocument.

  • Set the ColumnMapping.ProcessCode attribute to the ImportProcessCode.Internal value of the ImportProcessCode enumeration, if you are using early bound types. For a list of the ProcessCode values, see the picklist values for this entity.

    If the source data represents a note, map the text of the note to the Annotation.NoteText attribute. If you are working with Salesforce files, they are usually stored on the disk under unique identification numbers. To import an attachment, you must map a file identification number that is contained in the source file to the Annotation.DocumentBody attribute. The DocumentBody attribute stores the contents of the attachment.

    The import asynchronous job checks for mappings that have the source attribute name set to “true” and “false” to discover notes and attachments. If it finds an attachment mapping, it looks for the specified files on the disk and uploads the file contents as attachments into Dynamics 365. If a file is not found, an error is returned.

    If you do not provide mapping for an annotation (note) entity, the import job generates a default mapping for the note.


The maximum size of files that can be uploaded is determined by the Organization.MaxUploadFileSize property. This property is set in the Email tab of the System Settings in the Dynamics 365 application. This setting limits the size of files that can be attached to email messages, notes, and web resources. The default setting is 5 MB. However, an attachment size cannot exceed the maximum HTTP request size (the default is 16MB). For the change to take effect, reset Internet Information Services (IIS). To do this, click Start, click Run, type iisreset, and then click OK.

Import and export data maps

You can export an existing data map to an XML file and import XML data mappings into Dynamics 365. To export a data map from Dynamics 365, use the ExportMappingsImportMapRequest message. To import XML data mappings and create a data map in Dynamics 365, use the ImportMappingsImportMapRequest message.

See also

Import Data in Dynamics 365
Add Transformation Mapping
Add Transformation Mappings for Import