So you have upgraded your Microsoft Dynamics CRM 4.0 organization to Microsoft Dynamics CRM 2011, and you intend to export all upgraded customizations and import them in each of your development/test organizations so that your team can unleash all their creativity by designing new customizations and trying out new extensibility features.
Transporting all your upgraded customizations to another org may not always be successful on the first try. You may encounter various import errors along the way that would require fixes to your upgraded org and a few iterations of export and import. But fret not, as most of these errors are fairly legitimate and are due to the new restrictions imposed by the CRM 2011 solutions framework. They were put in place to help you ship solutions with more reliable customizations. The typical error is similar to this:
"The dependent component [missing Component Type] (Id=[missing Component Id]) does not exist. Failure trying to associate it with [dependent Component Type] (Id=[dependent Component Id]) as a dependency. Missing dependency lookup type = PrimaryKeyLookup"
Our team has tested upgrade and customization transport of hundreds of highly customized databases. In doing such exercise, we discovered that most import failures fall under the same few buckets. I’m going to talk about what causes these common errors and how you can fix them.
Invalid Dependencies
Microsoft Dynamics CRM 2011 Solution Components may depend on each other. These dependencies are tracked so that the system can prevent someone from accidentally deleting a solution component that is required by another solution component. Microsoft Dynamics CRM 4.0 also had dependencies between customizable items, but the infrastructure to track them is much more robust in Microsoft Dynamics CRM 2011.
For example, a custom attribute you create on the Account entity can be added to its FormXml, or as a view column or filter criteria in a SavedQuery. It can be referenced in a workflow, in a plugin assembly, or in e-mail templates. In CRM 4.0, it may be possible to delete this custom attribute even if the components mentioned are referencing it. This is no longer possible in CRM 2011, since the dependency infrastructure prohibits delete of a component until all references of other components to it are removed. So what happens if you upgrade an organization to CRM 2011 in this state?
Firstly, this will not prevent organization upgrade from succeeding. However, once you export your customizations and import them in another CRM 2011 org, it will fail when dependency calculation takes place (Note: Solution Import is now treated as a single transaction, hence one import error will halt the entire process and rollback all the components that have been previously imported). In your import job log, you will get an error with similar to this:
"The dependent component Attribute (Id=new_mycustomfield) does not exist. Failure trying to associate it with Template (Id=58817a33-e52f-e011-8acb-00155db059be) as a dependency. Missing dependency lookup type = PrimaryKeyLookup"
In this case, the attribute new_mycustomfield was deleted in CRM 4.0 though it is still referenced by an e-mail template. With this error, it is already clear which components are problematic. To fix this, the template mentioned should be opened in the e-mail template editor and all references to new_mycustomfield must either be removed or replaced with another attribute depending on the business need for the template.
Here are some common invalid dependency occurrences:
- Workflows/Processes depending on Attributes that no longer exist
- Plug-in Steps referencing Attributes that no longer exist
- FormXml referencing Attributes that no longer exist
- FormXml referencing a Lookup to a Relationship that no longer exists
- SavedQueries referencing Attributes that no longer exist (whether in the columns or filter criteria/fetchXml)
- Templates referencing Attributes that no longer exist
You can fix these invalid dependency errors as they come based on the import log’s error message. However, if you have a lot of these in multiple components in your upgraded organization, it will take a lot of time, as you will fix errors only one at a time (solution import halts on the first error and does not process the rest) and you will be doing multiple exports and imports of your customizations.
There is a way of dealing with all invalid dependencies at once. Invalid dependencies are represented by an entity in CRM 2011 (search Microsoft Dynamics CRM SDK for search for InvalidDependency Entity Messages and Methods), and by using the API, particularly the RetrieveMultiple message, on this entity, you will be able to retrieve a collection of invalid dependencies in your upgraded organization. Dump the contents of these records in a text file for reference and make sure to include the values for at least these attributes:
|
Property
|
Display Name
|
Description
|
|
existingcomponentid
|
Existing Object Id
|
This is the GUID of the component that references a missing component, which in our example is the e-mail template. This is most likely the component you will modify to fix the invalid dependency.
|
|
existingcomponenttype
|
Existing Object’s Component Type
|
This is an integer representing what type of CRM component existingcomponentid is. To map the numeric values to their more recognizable names, search the Microsoft Dynamics CRM SDK for "Global Option Set Values" and see the Component Type section.
|
|
missingcomponentid
|
Regarding
|
This is the id of the missing component which was deleted when the org was in v4 state.
|
|
missingcomponenttype
|
Type Code
|
Like existingcomponenttype, this represents what type of CRM component the missing component is.
|
With the information you can get from retrieving the entire collection of invalid dependencies, you can deal with them right away without even exporting and importing your customizations yet. Applying this practice can save you lots of time.
Missing Dependencies
While invalid dependencies involve broken components because they are referencing non-existing components that were deleted before upgrade to CRM 2011, ‘missing’ dependencies issues occur when a component is dependent on another component that either was not exported in your solution, or cannot be imported to the target organizations for valid reasons. This can be better illustrated by the following scenarios:
Workflows depending on e-mail templates that are personal or made personal
Personal e-mail templates cannot be a part of a solution nor can it be exported. Hence, if you try to export any solution having a workflow that references a personal template, you will get this warning before you export:
If you decide to proceed with exporting the solution and importing to an organization that does not contain this personal template, it will fail with the Missing Dependency error right before import begins. (Note: Add Required Components button as described in the warning message will not work either, because personal templates cannot be added to any solution)
To get past this error, before you export, you can either
- Make the template available to the organization
- Remove the workflow from the solution or delete it.
- Create a solution containing all other components except the workflow and export that instead.
Reports depending on child reports that are personal or made personal
Similar to the previous example, reports referencing other personal reports will yield the same result. In this case though, it is an option to convert the referencing report to personal as well so both the parent and child reports are personal and won’t be exported.
Workflows depending on e-mail templates in a different language that does not exist in target org
E-mail templates can come in different languages, even in previous Dynamics CRM versions. And as we’ve already implied, workflows can reference them as they can be used to send e-mails. So let’s say that, for example, your upgraded organization has an English (1033) base language with Japanese (1041) and German (1031) MUI packs installed and enabled. If you have workflows that use German or Japanese e-mail templates and you export, and then import the customizations into a pure English organization, import will fail while calculating dependencies because the templates in other languages, while they are processed, they are not created because their language does not exist in the target org.
Looking at the import job log, the template will have this warning: "You cannot import this template because its language is not enabled in your Microsoft Dynamics CRM organization."
While the workflow will have the error: "The dependent component Template (Id=abde9d8a-eb2f-e011-8acb-00155db059be) does not exist. Failure trying to associate it with Workflow (Id=2ef0864e-e6d9-4778-a1bb-858fe5e659cd) as a dependency. Missing dependency lookup type = PrimaryKeyLookup."
To get past this error, have all required MUI packs installed in the target organization. Or, if it is an option, package your customizations into different solutions such that the language-agnostic components are separate from the ones that depend on the existence of specific MUI packs.
Invalid Plugin Assembly/Steps Registration
This area is discussed in the Microsoft Dynamics CRM SDK so I will keep this short and quote some specifics along the way (search for "Upgrade Plug-ins and Custom Workflow Activities to Microsoft Dynamics CRM 2011", see "Post Upgrade Issues and Resolution" section).
Back in Microsoft Dynamics CRM 4.0, validations in plug-in registration were very limited. The system allowed incorrect values for plug-in images, entity attributes, and step registration attributes. In CRM 2011, this is no longer the case as full validation is already in place. So, again, what happens when you upgrade an organization to CRM 2011 having plug-ins registered incorrectly?
The short answer is, again, upgrade will not be blocked by such issues. However, exporting then importing them to another org is a different story as this full validation kicks in during import. To resolve import issues due to this, all plug-in registrations must be re-evaluated to make sure that they don’t fall under these known configuration issues (taken from SDK):
- Specifying an invalid attribute in an image or step. For example, the attribute name is not spelled correctly or the attribute does not exist in Microsoft Dynamics CRM 2011.
- Registering a pre-image for a CreateRequest or a post-image for a DeleteRequest.
- Specifying an incorrect deployment type. For example, registering a plug-in to execute on an assign of an account for deployment on Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access when that message and entity combination is supported only on the server.
Understanding these three major buckets will help speed up the process of getting your upgraded customizations to import in other CRM 2011 organizations, as around 90% of the ‘first-try’ import failures in our customer database upgrade testing fall under these three. Go forth and have fun exploring the new extensibility features in Microsoft Dynamics CRM 2011!
Cheers,
Greg Alicbusan
