Microsoft Dynamics CRM Online Data Migration Manager

Readme

April 2008


This document has important, late-breaking information about using Data Migration Manager to migrate data to Microsoft Dynamics CRM Online.

Contents

Data Migration Manager Documentation

System Requirements

Installation Instructions

Known Issues

Data Migration Manager Documentation

Microsoft Dynamics CRM Data Migration Manager Help

Data Migration Manager Help contains step-by-step instructions for working with the Data Migration Manager, as well as reference and troubleshooting information. You can open Data Migration Manager Help from the Help menu in Data Migration Manager.

Additional migration troubleshooting information is available in the Resource Center

System Requirements

This section describes the system requirements to run Data Migration Manager.

Data Migration Manager cannot be upgraded from prerelease versions

You cannot update prerelease versions of Data Migration Manager, such as Microsoft Dynamics CRM Live Early Access II (EA II) Data Migration Manager. Before you run Data Migration Manager Setup, you must uninstall the prerelease version.

Data Migration Manager cannot be run at the same time as Microsoft Dynamics CRM for Outlook

You cannot run the Data Migration Manager while Microsoft Dynamics CRM for Microsoft Office Outlook is running.

Temporarily disable Microsoft Dynamics CRM for Microsoft Office Outlook.

In the Notification area, click the Microsoft Dynamics CRM Application Host icon, and then click Disable CRM. The icon appears grey. Microsoft Dynamics CRM will be re-enabled the next time you start Outlook.

If you have closed Outlook, and receive an error message from Data Migration Manager stating that Outlook is still running, you need to use Task Manager to stop the Outlook.exe process.

Data Migration Manager should not be installed on a shared computer

Do not install Microsoft Dynamics CRM Data Migration Manager on a computer that is shared by multiple users. Data Migration Manager can only be used by the person who installs it.

Installation Instructions

Install Data Migration Manager:

1.       On the computer on which you plan to install Data Migration Manager, use Microsoft Internet Explorer to browse to your Microsoft Dynamics CRM Online server.

         If you cannot use Microsoft Dynamics CRM Online from this computer, you will not be able to install and use Data Migration Manager on this computer.

         If the Microsoft Internet Explorer Connect to dialog box is displayed, select the Remember my password check box.

         If you are using Windows Vista:

1.       In Control Panel, click User Accounts, and then click Manage Your Network Passwords.

2.       In the Store User Names and Passwords screen, click Add.

3.       In the Store Credential Properties screen, specify the name of your Microsoft Dynamics CRM Online server.

4.       In the Credential type section, select A Web site or program credential, click OK, and then click Close.

2.       Download Data Migration Manager and run the Setup program.

3.       On the Setup screen, click Install Microsoft Dynamics CRM Data Migration Manager, and follow the instructions in the setup wizard.

         If you choose to install Microsoft SQL Server Express, note that it cannot be installed on a compressed drive.

         If you choose to use an existing instance of SQL Server, note that it must be in the same domain as the computer on which you are installing Data Migration Manager.

Configure Data Migration Manager:

1.       On the Start menu, point to All Programs, point to Microsoft Dynamics CRM, and then click Data Migration Manager. It takes the Data Migration Manager a few minutes to start the first time.

2.       Complete the steps in the configuration wizard.

Note: If you are using a computer running SQL Server, rather than SQL Server Express, by default the configuration wizard will attempt to connect to the Microsoft Dynamics CRM instance on your server. If you prefer to use a different instance, on the Specify SQL Server page, specify the instance name in the format server_name/instance_name.

Start the Data Migration Manager:

         On the Start menu, point to All Programs, point to Microsoft Dynamics CRM, and then click Data Migration Manager.

Known Issues

Date data, in unexpected formats, may migrate after conversion to a format consistent with your date format setting

Microsoft Dynamics CRM 4.0 Data Migration Manager authenticates the date data, in your source data, during migration. In cases where the date data is not in the format specified by your date-format setting, Data Migration Manager displays an error. However, there are some cases in which date data is not in the expected format in the source data, but Data Migration Manager converts the data to an expected format (without displaying an error) and migrates the data.

For example, if you were migrating data for which the date format had been set as yyyy/mm/dd (April 15, 2007 would be 2007/04/15). The following table is an illustration of how Data Migration Manager would handle the inconsistent formats.

Source data

Migrated data

Comments

4/15/07

Not migrated.

15 is not a valid month, so Data Migration Manager displays an error.

04/15/2007

2007/04/15

Data Migration Manager interprets 2007 (where the system expects a day) as the year and so converts the entire date string based on the assumption that 2007 represents a year. Therefore, no error is displayed in this case, and data is migrated after Data Migration Manager converts the date data to a format consistent with your date format setting.

 

If Data Migration Manager displays errors or migrates date/time data incorrectly, correct the inconsistencies in the source comma-separated values (CSV) file and try migrating the data again.

Numeric data with very large values, or many digits after the decimal point, may be partially truncated during migration

Microsoft Dynamics CRM 4.0 includes default limitations on the precision of very large numbers, and numbers with many digits after the decimal point. Although these limitations can be modified through customization in the Web application, migrating data by using Data Migration Manager with default precision settings in the Web application can sometimes result in truncation of numeric data that falls outside the range of these settings. Even if truncation occurs, Data Migration Manager will not display an error message and will migrate the data.

If you are migrating numeric data to Decimal, Float, or Money attributes, used by entities in Microsoft Dynamics CRM 4.0, verify that your source data does not contain data that falls outside of the expected range. If your source data contains very large numeric values, or values with many decimal places, and truncation is not acceptable during migration, you can customize the target attributes through the Settings area of the Web application before starting the migration.

Similarly, if you choose to create custom attributes from Data Migration Manager during the migration process, there are limitations on the precision supported by Data Migration Manager, as shown in the following table.

Attribute type

Maximum precision

Decimal

10 digits past the decimal point

Money

4 digits past the decimal point

Float

5 digits past the decimal point

 

Important: Any data that exceeds these precision values will be truncated during migration, and Data Migration Manager will not display an error message.

Even if the data falls withing the maximum precision values for these three data types, for very large numbers there may still be cases in which truncation occurs. The following table includes examples of truncation during migration of very large numbers and numbers with many digits after the decimal place.

Data type

Value in source data

Value after migration

Comments

Decimal

999,999.1234567891

999,999.1234567890

Even with a default precision of 10, data is truncated because of the large value.

Decimal

99,999,999.1234567891

99,999,999.1234568000

Money

922,337,203,685,476.1234

922,337,203,685,476.0000

Even with a default precision of 4, data is truncated because of the large value.

Money

92,233,720,368,547.1234

92,233,720,368,547.1000

Money

92,233,720,368,54.1234

9,223,372,036,854.1200

Float

99,999,999,999.12345

99,999,999,999.12340

Even with a default precision of 5, data is truncated because of the large value.

If creation of a new custom attribute fails during migration, data in that attribute is not migrated

If you choose to create a custom attribute for a column of data in your source CSV file, but the Data Migration Manager fails to create the attribute during the migration process, the data in the source column is not migrated to Microsoft Dynamics CRM.

However, the Data Migration Wizard may display a message on the Conversion Errors screen stating that you can continue the migration "without migrating the rows that have errors." Because the custom attribute could not be created for all rows in your source CSV file, this message implies that none of the data will be migrated. In reality, if there are no other errors, data in other columns will be migrated successfully.

To correct this issue, create the custom attribute in the Microsoft Dynamics CRM Web application and add the missing data manually to the records that were migrated. Alternatively, resolve all the errors reported on the Conversion Errors screen before uploading any of the data to Microsoft Dynamics CRM.

The default SalesForce.com data map for the Contract entity must be customized to migrate contract data successfully

If you migrate contract records from SalesForce.com to Microsoft Dynamics CRM without data for the CustomerId and BillingCustomerId attributes in Microsoft Dynamics CRM, Data Migration Manager displays errors. SalesForce.com data has only one AccountID column that corresponds to these two attributes in Microsoft Dynamics CRM. Both attributes in Microsoft Dynamics CRM are required. However, the Data Migration Manager does not support direct 1:2 column mapping for Reference attributes.

To resolve this issue, you can map one source-data column to one of the attributes in Microsoft Dynamics CRM, and then use a transformation mapping to map the same source-data column to the second attribute in Microsoft Dynamics CRM. Alternatively, you can use a transformation mapping to map the source column to both target attributes.

The sample SalesForce.com data map for Microsoft Dynamics CRM Data Migration Manager includes an example of this type of mapping. To convert contract data successfully from the format that SalesForce.com uses to the format used by Microsoft Dynamics CRM, you must customize the default SalesForce.com data map.

To prevent errors during conversion, customize the SalesForce.com data map to use a transformation that copies AccountId attribute data to both CustomerId and BillingCustomerId.

<TransformationMap Id="75671888-718c-4868-a472-10365225a639">
 <TransformationTypeName>Microsoft.Crm.Transformations.AssignValue</TransformationTypeName>
 <ProcessCode>Process</ProcessCode>
 <InputParameterMaps>
 <SingletonInputParameterMaps>
 <SingletonInputParameterMap Id="7de9a405-7b55-47d1-8c61-d622b64b8096">
 <ParameterSequence>1</ParameterSequence>
 <DataTypeCode>Reference</DataTypeCode>
 <Data>AccountId</Data>
 </SingletonInputParameterMap>
 </SingletonInputParameterMaps>
 <ArrayInputParameterMaps />
 </InputParameterMaps>
 <OutputParameterMaps>
 <OutputParameterMap Id="9e63fc9f-7acf-4e23-9782-4547f6b54b4d">
 <ParameterSequence>1</ParameterSequence>
 <Data>billingcustomerid</Data>
 <LookupMaps>
 <LookupMap Id="2f5a6a93-84bd-44bc-b820-05d41583c479">
 <LookupEntityName>Account</LookupEntityName>
 <LookupAttributeName>Id</LookupAttributeName>
 <LookupType>Source</LookupType>
 <ProcessCode>Process</ProcessCode>
 </LookupMap>
 <LookupMap Id="2f5a6a93-84bd-44bc-b821-05d41583c479">
 <LookupEntityName>account</LookupEntityName>
 <LookupAttributeName>accountid</LookupAttributeName>
 <LookupType>System</LookupType>
 <ProcessCode>Process</ProcessCode>
 </LookupMap> 
</LookupMaps>
 </OutputParameterMap>
 </OutputParameterMaps>
 </TransformationMap>
 
<TransformationMap Id="75671888-718c-4868-a472-10365225a639">
 <TransformationTypeName>Microsoft.Crm.Transformations.Replace</TransformationTypeName>
 <ProcessCode>Process</ProcessCode>
 <InputParameterMaps>
 <SingletonInputParameterMaps>
 <SingletonInputParameterMap Id="7de9a405-7b55-47d1-8c61-d622b64b8096">
 <ParameterSequence>1</ParameterSequence>
 <DataTypeCode>Reference</DataTypeCode>
 <Data>AccountId</Data>
 </SingletonInputParameterMap>
 <SingletonInputParameterMap Id="577b741b-7b7c-41ec-adf0-5c337ca50e4e">
 <ParameterSequence>2</ParameterSequence>
 <DataTypeCode>Value</DataTypeCode>
 <Data>000000000000000AAA</Data>
 </SingletonInputParameterMap>
 <SingletonInputParameterMap Id="577b741b-7b7c-41ec-adf0-5c337ca50e4e">
 <ParameterSequence>3</ParameterSequence>
 <DataTypeCode>Value</DataTypeCode>
 <Data></Data>
 </SingletonInputParameterMap>
 </SingletonInputParameterMaps>
 <ArrayInputParameterMaps />
 </InputParameterMaps>
 <OutputParameterMaps>
 <OutputParameterMap Id="9e63fc9f-7acf-4e23-9782-4547f6b54b4d">
 <ParameterSequence>1</ParameterSequence>
 <Data>customerid</Data>
 <LookupMaps>
 <LookupMap Id="2f5a6a93-84bd-44bc-b820-05d41583c479">
 <LookupEntityName>Account</LookupEntityName>
 <LookupAttributeName>Id</LookupAttributeName>
 <LookupType>Source</LookupType>
 <ProcessCode>Process</ProcessCode>
 </LookupMap>
 <LookupMap Id="2f5a6a93-84bd-44bc-b821-05d41583c479">
 <LookupEntityName>account</LookupEntityName>
 <LookupAttributeName>accountid</LookupAttributeName>
 <LookupType>System</LookupType>
 <ProcessCode>Process</ProcessCode>
 </LookupMap>
 </LookupMaps>
 </OutputParameterMap>
 </OutputParameterMaps>
 </TransformationMap>

Some records are migrated to Microsoft Dynamics CRM with a default status

Some entities in Microsoft Dynamics CRM include business logic for the transition from one status (state) value to another. Status (state) values in many entities are associated with specific status reason (status) values. Similarly, some records can only be associated with other records when each record has a specific status or status reason. This type of behavior varies greatly from one CRM system to another. Therefore, the Microsoft Dynamics CRM Data Migration Manager partially supports setting the status (and corresponding status reason) for certain entities.

By default, all records are created with their default status. Data Migration Manager then attempts to set the correct status for these records, based on the status of records in your source data, or the status of records related to the records you are migrating. However, if this is not possible because of differences in business logic, an error occurs and the record remains with its default status.

Microsoft Dynamics CRM includes special business logic for status and status-reason transitions for the following entities:

For all entities except Opportunity, data migration errors can cause records for these entities to be created with default statuses. However, full business logic is supported for the Opportunity entity.

User data with inconsistent capitalization may not be migrated correctly

Mapping functionality in the Data Migration Manager is not case sensitive. However, the conversion process itself is case sensitive. Therefore, user data that had been mapped without any errors may be converted incorrectly later in the migration process. Similarly, record ownership may become incorrect due to inconsistent capitalization of user data in the source data.

For example, in source data in which unique users were identified by their e-mail addresses, data maps would consider the following values to be identical: Name@example.com, name@Example.com, and name@example.com. You would be able to map all three of these values to a single user in Microsoft Dynamics CRM. However, the conversion process would treat these three values as unique, and may display an error or convert the user data (including record ownership) incorrectly.

Make sure that the source data you choose to migrate does not include user data with inconsistent capitalization. Similarly, if you are using a data map, make sure that the values specified in your data map are consistent with the capitalization in your source data.

Stand-alone migration of user data is not supported

User data is necessary to determine ownership of the records that you are migrating. Therfore, migrating only user data by using Data Migration Manager, without migrating associated records, is not supported. Always migrate user data with the other record types that the users own.

Source data files must be smaller than 32 megabytes

Each source-data file that you are migrating using the Data Migration Manager must be less than 32 MB in size. If any of your source data files are larger than 32 MB, split the data into multiple files that are smaller than 32 MB. Make sure to include the header row in each file before you begin the migration process.

Note: You can increase the default file size limit of 32 MB by editing the web.config configuration file in the Program Files\Microsoft Dynamics CRM\Data Migration Manager\dmclient\res\web folder. However, doing so can degrade the performance of Data Migration Manager. We recommend that you split the data into multiple files instead of increasing the default file size limit.

Custom datetime attributes with Date and Time format cannot be created from the Data Migration Wizard

You can create custom datetime attributes of Date Only format by using the Data Migration Wizard. However, you cannot create datetime attributes with the Date and Time format in the Data Migration Wizard.

If you have source data with an attribute that includes date and time data, you can migrate this data to a custom Microsoft Dynamics CRM Online datetime attribute set to the Date Only format during migration. The format you select only affects how date and time information is displayed in the Microsoft Dynamics CRM Online user interface. None of your data is lost during the migration process.

You can resolve this issue by changing the display format to Date and Time in the Microsoft Dynamics CRM Online Web application after your data has been migrated. However, if you want to avoid changing the format after migration, create the custom datetime attribute you need in the Web application before migration, and then migrate your date and time data into this new custom attribute.

Configuring Data Migration Manager fails for users without Administrator privileges when using a remote instance of SQL Server

If Microsoft SQL Server is not installed on the same system as Microsoft Dynamics CRM Online Data Migration Manager and if you do not have Administrator privileges on the system where you are running Data Migration Manager, you will not be able to configure Data Migration Manager.

Before configuring Data Migration Manager, check to make sure that you have the necessary privileges and that the SQL Server Browser Service program is currently running.

Users created by previous migration processes are not available until you close and reopen Data Migration Manager

If you create user records from Data Migration Manager, complete the migration process, and then try to migrate additional user records without closing Data Migration Manager, the users you created in the first migration process do not appear in the list of existing Microsoft Dynamics CRM Online users during the second migration process.

Similarly, users created directly in the Microsoft Dynamics CRM Online Web application while the Data Migration Manager was running do not appear in the list of existing users. This can prevent you from mapping additional user data to these new user records, and may affect mapping of record ownership information.

If you have created user records in one migration process, and want records that you migrate during a second migration to either map, or refer, to these user records, you must refresh Data Migration Manager by closing, and then reopening, Data Migration Manager.

Source data cannot be migrated to custom drop-down list (picklist) attributes if you choose not to automatically customize Microsoft Dynamics CRM Online list values

Using the Data Migration Manager, you can add custom drop-down list (picklist) attributes and you can add new values to existing drop-down lists. On the Get Started page in the Data Migration Wizard, you can choose whether to automatically customize Microsoft Dynamics CRM Online list values. If you leave the To accommodate the source data, automatically customize Microsoft Dynamics CRM Online list values and length of attributes check box selected, Data Migration Manager automatically detects unmapped custom drop-down list values in your source data and adds them as custom drop-down list attribute values to existing Microsoft Dynamics CRM Online attributes.

However, if you clear this check box, custom drop-down list attribute values are not added to Microsoft Dynamics CRM Online, causing migration of some records to fail.

To prevent this problem from occurring, perform one of the following procedures:

Source data intended for the Service attribute in Campaign Activity and Campaign Response entities cannot be migrated

In Microsoft Dynamics CRM Online, both the Campaign Activity and Campaign Response entities include a Service (serviceid) attribute that does not appear by default on the forms for these two entities. The Service attribute is a reference (lookup) attribute. However, there are no valid entities that this attribute can reference.

Therefore, if your source data includes data that you want to migrate to the Service attribute in either of these two entities, you will not be able to do so. In the Data Migration Wizard, you will see a blank screen where you would otherwise be prompted to map the column in your source data to a referenced entity.

To avoid this issue, do not map source data to the Service attribute in the Campaign Activity or Campaign Response entities.

 

Documentation Feedback

The Microsoft Dynamics CRM Online Documentation Team welcomes your suggestions and comments about the documentation. You can quickly and directly send e-mail feedback to Documentation Feedback. All feedback must be in English. Your feedback will be used to make improvements to the Help and shape the content delivered to the Resource Center.

Copyright

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

2008 Microsoft Corporation.  All rights reserved.

Microsoft, Microsoft Dynamics, Outlook, SQL Server, Visual Studio, Windows, and Windows Server are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.