Migrating Notes and Attachments using Data Migration Manager

In Microsoft Dynamics CRM 3.0, there was no straight-forward way to import a bunch of attachment into CRM without writing some code. This has changed in 4.0. The Data Migration Manager supports migrating Notes and Attachments (collectively called annotations) to CRM. You only need to know a few tricks to get it done, as follows:-

1. Create separate CSV files for Notes and Attachments. One CSV file can have either notes or attachments, not both. The sample CSV files for Notes and Attachments are shown in Fig 1 and Fig 2 respectively.


Fig 1 – Sample Notes.csv


Fig 2 – Sample Attachments.csv file

2. Do not include the IsDocument column in the CSV file. The DMM will automatically fill this value. If you don’t want to remove this column from the CSV file, make sure that you “Ignore” this column when DMM asks you to map it to a CRM attribute.

3. If you are migrating attachments, store all the attachment files, with unique names in one of the following directories:-

a. The folder in which the CSV file that contains attachment records is present.

b. A subfolder named “Attachments” in ‘a.’

c. A subfolder named “Documents” in ‘a.’

Fig 3 shows the CSV files that we are migrating. In this example, we will use option c above. Fig 4 shows the attachment files inside a subdirectory ‘Document’.


Fig 3 – The CSV files being migrated


Fig 4 – Attachment files inside subdirectory ‘Documents’

4. Have a column in the CSV file that contains the name (not the path) of the attachment file on disk. Note that you don’t need to store the contents of the attachment in the CSV file. You should store only the name of the file. The DMM will search for the attachments in the 3 locations specified in Step 3. This column must be mapped to the ‘documentbody’ (Display Name- “Document”) column of the annotation entity in DMM. This is described in Step 6. In Fig 2 above, note the column with heading “Document”. This column is mapped to the field ‘Document’ as shown in Fig 6 below.

5. Map the CSV files which contain annotations to the Note entity in DMM as shown in Fig 5 below. If the CSV file contains attachments, check the “Includes Attachments” checkbox. If the CSV file contains notes, leave the checkbox unchecked.


Fig 5 – Mapping the annotation files

6. If you are migrating attachments, map the column described in Step 4 to the “Document” attribute as shown in Fig 2. If the current file doesn’t contain attachments, then you will not see the Document attribute in the columns list. Also, you will never see the IsDocument field in the columns list.


Fig 6- Map the Attachment name column to ‘Document’

7. Map all other columns as usual. The ‘Regarding’ column specifies the CRM record each annotation is attached to. It is no different from a lookup.

Note that the filenames of the attachments on disk can be different from what goes in the ‘FileName’ column. For example in the current example, the filenames of the attachments are ‘Costing.pdf’, ‘Members.xlsx’ and ‘Items.txt’, whereas the names of these files on disk are ‘100567’, ‘100879’ and ‘100989’ respectively.

The user will never see what filenames (identifiers) the attachments had on disk. These identifiers are used for the sole purpose of identifying an attachment file uniquely. The file name of the attachment that is visible to the CRM user is the one that is stored in the ‘FileName’ field. If an attachment in CRM has blank ‘FileName’ then its name is shown as ‘untitled.txt’ by default. So, if you want the user to see the filenames you should have a column in your CSV file which contain the user friendly filenames of attachments and this column should be mapped to the ‘FileName’ field. The values in this column i.e the one which is mapped to ‘FileName’ field can be duplicates, unlike the values in the column which is mapped to the ‘Document’ field.

To use an existing map to migrate annotations, one needs to add the following two AttributeMaps to the Data Map.

<EntityMap TargetEntityName="annotation" SourceEntityName="Attachment">



















The first attribute map specifies whether the CSV file contains notes or attachments. The SourceAttributeName field can contain special values ‘True’ or ‘False’. If The SourceAttributeName value is False, then the CSV contains notes, else attachments. The TargetAttributeName is ‘isdocument’. This field never shows up in the DMM. Its value is populated automatically. Also, the ProcessCode for this mapping is set to ‘Internal’ .

The second attribute map specifies which source field contains unique identifiers of attachment files. This source field has ‘documentbody’ as the target field. This attribute-map must be added ONLY if the source file contains attachments.

Well, that’s all the magic behind migrating annotations through the Data Migration Manager. The DMM reads the attachments one by one from the disk during upload phase and creates them on the server. These notes and attachments are visible to the user in the Notes tab of the CRM record page to which these annotations are attached. Fig 7 shows the notes and attachments attached to the account ‘AccountOne’ after the migration is complete.


Fig 7 – Notes and Attachments of ‘AccountOne’


Tushar Bhatia

Comments (23)

  1. Josie Fleschute says:

    This should really make migrating a piece of cake.  Thanks Tushar!

  2. This does make migrating notes and attachments much easier. However, it would be nice if it included how to assign values to the MS-CRM Note CreatedOn and CreatedBy values. I haven’t seenhow to do this yet and migrating the notes with out these ‘history’ tags is less than ideal. Maybe that’s in another article, I’ll keep looking.

    Don’t get me wrong, this ability to easily migrate notes is great, just needs alittle more to hit all the usual requirements.



  3. Joel says:

    Can we use a similar way for marketing list using attachment?

  4. Phil Edry says:

    Thanks for the helpful post — I link to it in my latest blog post on how to hack the Data Migration Manager to migrate email attachments: http://dynamicscrmblog.com/9

    I went about it in an inelegant (an unsupported) way, but it works. If you folks know of a better way, let me know!


  5. Thanks Tushar, for a most instructive tutorial.

    I tried tyour approach to migrate data from Act! 6, but hit this issue:

    Since my annotations contain carriage returns, the Data Migration Manager will not import them properly, even if I encapsulate my CSV strigns between quotes.  Any idea how I can circumvent that without having to write code?



  6. In this entry I am going to talk about different features in Data Migration Manager(DMM) where error

  7. In this entry I am going to talk about different features in Data Migration Manager(DMM) where error

  8. In this entry I am going to talk about different features in Data Migration Manager(DMM) where error

  9. Kannan says:

    I want to add and rety the notes from any entity

    Please help me

  10. Al says:

    If a file is to be attached to more than one contact or account, how is this done?

  11. ragnarok89 says:

    How would  I import a file and link it to 2 or more contacts?

  12. Christian says:

    How do I download the annotation attachment from the CRM database to the local disk?

  13. Tushar says:

    Hi Christian

    Plz see the last sentence of this blog post. You can download the attachment by accessing it through the CRM record form (Notes Tab) to which it was attached.

    You can also retrieve this record programmatically from the SDK by using the RetrieveRequest or RetrieveMultipleRequest on annotation entity.

    Let me know if this doesnt answer your question.


  14. Tushar says:

    You cannot link a file to more than one record. You have to create separate copies of the file and link each one separately.

  15. Joe Public says:


    How can you import a note that consists of more than one line?  The importer treats each line a new import row.



  16. Chris says:

    How do I get the Regarding field in my excel spreadsheet? I’m trying to export from CRM 3 (and have no SQL experience!)

  17. Arlene says:

    Can I use Data Migration Manager to upload marketing list?

  18. Raja Islam says:

    Hi Tushar,

    Thanks for such a helpful blog.


    Raja Islam

  19. Waqar says:

    Good article!

    It would be nice if we can have another article explaining the export of Notes/Attachments out of CRM 4.0.

  20. Kristoffer John De Vera says:


    Great article.

    I would want to ask how were you able to migrate the emails?

    My companies emails contain html so i find it hard to save it in a csv file.

    Also there are emails (set in the To, From, CC, etc.) that are not in the system which cause reference error.

    Hope you can help.

    Thanks in advance.

  21. Sekhar Ananth says:


    Thanks for the very useful blog on importing Notes to CRM 4.0.

    However, I wonder how the reverse can be accomplished..(ie) Exporting Notes and Contacts from CRM 4.0 Is there an easy way to EXPORT Notes and Attachments along with Contacts? Please let me know.




  22. Positively says:

    Hi – Can I just use the Import Wizard to import Notes for Accounts in CRM 4.0 or do I have to use the Data Migration Manager?  I've tried the Import Wizard but it tells me "The source data is not in the required format.", Column Heading "Regarding", Column Value "Test Account One", etc. and I don't seem to be able to find anywhere that tells me what the format for the "Regarding" column should be.


  23. Sushma says:

    Hi, I have increased the file size limit in web.config to 51200(maxRequestLength) and even updated the same in settings>administration>system settings>email tab as well. But the DMM is throwing an error "The file cannot be attached because it exceeds the maximum size limit." Please guide me!!

    Thanks' Sushma

Skip to main content