When performing customizations in Dynamics 365, it is important to transfer these changes in a safe and reliable way from your required source system (DEV) to the desired target system (UAT, ACC or PROD). To facilitate this process, Microsoft introduced the concept of Managed & Unmanaged Solutions in Dynamics CRM 2011 and improved this process even further in the latest Dynamics 365 versions.
An unmanaged Solution is used in your DEV instance to perform your customizations. It is still under development or isn’t intended to be distributed. Once the unmanaged solution is complete and you want to distribute it, you can export it and package it as a managed solution. This can also be used when you are an ISV and want to protect your IP.
But what is the best way to transfer solutions from your source (development) instance to other target instances (ACC, UAT or PROD)? This seems to be a point of discussion between several CRM consultants and deserves some extra clarification in this blogpost.
In the past versions of Microsoft Dynamics CRM (prior to Dynamics 365), most of the code deployments were done via unmanaged solutions as this was regarded as the fastest way. Working with managed solutions was considered a tricky challenge, and issues often required a holding solution (and lots of time!) to get fixed.
An unmanaged solution can be described as a container, combining multiple customizations. The container can be imported as an unmanaged solution in your target system and will transfer all your customizations that are available in the solution. However, deleting the unmanaged solution will leave all the individual components untouched! This would require you to manually delete all the individual components in the target instance, in case something goes wrong. To summarize, here are some risks you can encounter with unmanaged solutions:
- Deleting an unmanaged solution in your target instance does not delete the individual customizations in the solution.
- Unmanaged customizations can be changed from within the target system, and thus creating a conflict between your source and target instance.
- It is not possible to undo or roll back the changes made via an unmanaged solution
Using managed solutions to transfer customizations has some advantages. You can control which elements can(not) be customized in your target instance. This way you are sure that all customizations are pushed correctly from within your source entity to your target entity, which will help keeping both instances in sync. Another great advantage is that you can use versioning and patching to effectively handle your solution changes (more info to follow below).
There are however also some risks involved when using managed solutions, especially when deleting a managed solution. This will also trigger the deletion of all data stored in custom entities AND all data of custom field in system entities, that are a part of your managed solution. If your customer is already up and running, this will have a huge negative impact. In order not to lose your data, we suggest never deleting/uninstalling managed solutions, but advise on updating the managed solutions via patches or upgrades.
Adding/Removing components in another environment
Microsoft Dynamics 365 provides us with some interesting versioning, patching and cloning functionalities. We will use the following example to illustrate the benefits of using managed solutions to transfer customizations between a source and a target environment.
1. We have created an unmanaged solution “C-Clear Customizations” (version 18.104.22.168) in our source organization, which contains 5 components:
a. Entities: Contact role, contact, account
b. Workflow: Update contact
c. Business rule: Fill in start date of contact role
Note: An initial solution version can be named version 22.214.171.124 (major.minor.build.revision), but you can also use a date format 2018.04.10.01 (yyyy.mm.dd.revision).
2. We have imported this as a managed solution into our target environment.
3. Next, we decide that a field on our “Contact Role” entity is no longer required. We decide to remove the field from the form and delete it in our source environment. We save the solution manually as a higher revision (126.96.36.199) and import the managed one into our target environment. The result will be:
a. The field is correctly removed from the form
b. The field is not deleted inside your target environment! this way, there is no risk of deleting any important old data. To indicate that the field is no longer in use, we advise to add (DELETE) to the label of the field. This way it is clear to other users that the field should not be used. This can be done via the customizations (not via the solution) inside your target environment. Example:
4. As an additional test, we decide to remove (not delete!) the workflow “Update contact” from our source solution. We also decide to change the version number of our source afterwards manually to 188.8.131.52 again and leave the target as 184.108.40.206, but this will have no negative impact on the following steps.
5. We will use the option “Clone a patch” to generate a patch (version 220.127.116.11) of the unmanaged solution. This version number must have a higher build or revision number than the version number of the original solution. The patch will by default not contain any data. We can use the patch to add minor improvements and transfer them easily to the target environment. This process will go faster, as it does not include the entire solution. It also limits the risks of unintendedly importing changes - which were not yet ready - as you can specifically narrow down the content of the patch.
It is possible to have multiple patches at the same time. Keep in mind however that once you have created a patch, you can only perform changes in the patch and no longer within the initial solution!
In the following scenario, we have decided to import the first patch to our target environment and leave the second patch in our source:
6. When a patch is considered ready, you can import it into production. When all patches are ready, you can click on the button “Clone to Solution”.
This will combine the original solution and all its patches into a new solution with a higher version 18.104.22.168. The source solution will no longer contain three solution lines, but only one (which is unlocked and can be directly edited). The description field will indicate that this is an upgrade of your original solution.
7. Import this solution into your target environment. You will receive the following message:
8. It is important that “Stage for upgrade” is flagged. For the second option, you need to choose between maintain or overwrite customizations. When you are not sure if any conflicting customizations were directly performed on the target environment, it is advised to choose the option “maintain customizations”. Otherwise, you could potentially overwrite necessary customizations.
9. Once the import is successfully completed, click on the button “Apply Solution Upgrade”. This will combine all solutions and patches in the target environment into one solution record.
10. As a result, we will notice that our target environment now correctly contains only one solution record with version 22.214.171.124. Be aware: this will only happen for managed solutions! Applying a solution upgrade to an unmanaged solution will not rollup the original and patched solutions into one.
Even more interesting is that the workflow “Update contact” (which was removed from the solution in our source environment – see step 4) is now no longer present in our target environment! We can conclude that removing it in the source has led to a deletion within the target environment.
What will the user see?
Most projects contain a variety of managed and unmanaged solutions. If they are referencing the same object, the question is: what will the user see? In most scenario’s, you have your base layer of the system. On top of that is the managed solutions (one extra layer per managed solution). On top of all those layers, we will find the final layer containing all unmanaged customizations. An exception is provided when a user installs a managed solution and selects the option “overwrite customizations”, after which the managed layer will be applied on top of all the rest.
Another exception is provided with the fact that the order in which solutions are imported matters! If you install a solution B after solution A (both referencing the same objects), the customizations of the last one (B) will win. However, if you would afterwards apply another patch 126.96.36.199 of solution A, the patch is regarded as if it was installed prior to solution B – thus, solution B would still win. When solution A is cloned to a higher minor version 188.8.131.52 and installed, the customizations of this version will be the ones visible by the end user. A is then regarded as a complete new solution installed after B, and not just a minor patch before B.
Want to learn more?
Feel free to check out the following official documentation by Microsoft:
And stay tuned on our C-Clear blog!