Microsoft Dynamics CRM 4.0 Data Migration Manager

Readme

December 2007


This document provides important, late-breaking information about Microsoft Dynamics CRM 4.0 Data Migration Manager.

Contents

Setup Known Issues

Feature Area Known Issues

Microsoft Dynamics CRM Documentation

Documentation Feedback

Setup Known Issues

This section describes known issues that may occur when you install the Microsoft Dynamics CRM 4.0 Data Migration Manager.

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

Microsoft Dynamics CRM will be re-enabled the next time you start Outlook.

The version of the Data Migration Manager must exactly match the version of Microsoft Dynamics CRM to which you are connecting

If the version of Data Migration Manager you are using does not match the version of Microsoft Dynamics CRM to which you are trying to connect, Data Migration Manager may stop responding or the sign-in screen may go blank. To connect Data Migration Manager to Microsoft Dynamics CRM, the build numbers for both applications must be an exact match (for example, 4.0.7333.3). If the versions do not match, no specific error message will be displayed.

If the Data Migration Manager sign-in screen goes blank for an extended period of time, the versions may not match between Data Migration Manager and Microsoft Dynamics CRM. Verify that you are working with identical versions of both applications.

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.

Help for Data Migration Manager Setup may not be displayed in the correct language if you uninstall the application and then reinstall it in a different language

If you install Data Migration Manager in one language, uninstall the application, and then reinstall Data Migration Manager in another language, Help for Setup may be displayed in the language of the first installation.

To resolve this issue, delete the EnviromentDiagnostics.chm file from the temporary folder.

  1. Start Windows Explorer and locate the temporary folder.

    By default, the temporary folder is located in the following folder, where User is the name of the user that installed Data Migration Manager:

    Drive:\Documents and Settings\User\Local Settings\Temp

    On Windows Vista, the folder is located in the following folder, where User is the name of the user that installed Data Migration Manager:

    Drive:\Users\User\AppData\AppData\Local\Temp

  2. Right-click the file named EnviromentDiagnostics.chm, and then click Delete.
  3. Run Data Migration Manager Setup again.

Feature Area Known Issues

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

Microsoft Dynamics CRM 4.0 Data Migration Manager validates 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 describes 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 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.

Data Migration Manager fails to create custom entities or attributes with identical names or when their names differ only in capitalization of the letter i in Turkish

If you try to use the Turkish language version of Data Migration Manager to create custom entities with names that are identical (such as indigo and indigo) or that differ only in the capitalization of the letter i (such as indigo and Indigo), Data Migration Manager will not create the second instance of the entity or attribute. No error message will be displayed during or after migration.

Attempting to create custom attributes with identical names, or names that differ only in the capitalization of the letter i, during migration can cause the Turkish version of Data Migration Manager to stop responding.

Avoid using the Turkish version of Data Migration Manager to create custom entities or attributes that contain the letter i. The Microsoft Dynamics CRM 4.0 Web application does not have these issues. Therefore, if you want to create custom entities or attributes in Turkish that contain the letter i, create these entities or attributes through the Settings area in the Web application before migrating your data. Then, use Data Migration Manager to migrate your source data into these new entities and attributes.

Numeric data with very large values or many digits after the decimal place 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 place. 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, 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 resported 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 successfully convert contract data 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 provides only partial support for 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 an appropriate 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 the Opportunity entity, 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.

"The Data Migration Manager encountered an error while setting up the temporary migration database. Restart the Data Migration Manager, and then try migrating the data again." error message displayed in Data Migration Wizard

One possible source of this error message may be the UserReplicationID registry key. You can resolve this issue by deleting the registry key, restarting Data Migration Manager, and signing in again.

You can find this registry key in the following path (depending on your system type):

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.

Standalone migration of user data is not supported

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

Source data files must be smaller than 32 MB

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. 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 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 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 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 SQL Server

If Microsoft SQL Server is not installed on the same system as Microsoft Dynamics CRM 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 users during the second migration process.

Similarly, users created directly in the Microsoft Dynamics CRM 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 to 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 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 or not to automatically customize Microsoft Dynamics CRM list values. If you leave the To accommodate the source data, automatically customize Microsoft Dynamics CRM list values and length of attributes check box for this option 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 attributes.

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

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

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

In Microsoft Dynamics CRM, the Campaign Activity and Campaign Response entities both 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.

Microsoft Dynamics CRM Documentation

Microsoft Dynamics CRM Data Migration Manager Help

Data Migration Manager Help provides 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.

Microsoft Dynamics CRM Implementation Guide

The Microsoft Dynamics CRM Implementation Guide is available for download. The documents provide the system requirements and installation instructions to use to install Microsoft Dynamics CRM 4.0.

This implementation guide is written for the team of people responsible for deploying Microsoft Dynamics CRM 4.0.

Microsoft Dynamics CRM SDK

The Microsoft Dynamics CRM Software Development Kit (SDK) for developers, system customizers, and report writers is available for download. The SDK package covers the following topics:

Additionally, you’ll find a user interface style guide, walkthroughs, tools for registering plug-ins and custom workflow activities, and lots of sample code. The documentation also is posted live on the Microsoft Dynamics CRM Developer Center, along with other helpful links for developers and system customizers.

Documentation Feedback

The Microsoft Dynamics CRM 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, and Visual Studio are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.