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">
<AttributeMaps>
:
:
<AttributeMap>
<SourceAttributeName>True</SourceAttributeName>
<TargetAttributeName>isdocument</TargetAttributeName>
<ProcessCode>Internal</ProcessCode>
</AttributeMap>
:
<AttributeMap>
<SourceAttributeName>Name</SourceAttributeName>
<TargetAttributeName>documentbody</TargetAttributeName>
<ProcessCode>Process</ProcessCode>
</AttributeMap>
:
:
</AttributeMaps>
</EntityMap>
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’
Cheers,
Tushar Bhatia