Internal storage of SiteMap and Form customization in managed solution packages
Solution is a fantastic feature that will be released with the Microsoft Dynamics CRM 2011. Refer to this blog for its introduction: CRM 2011 solutions buisness apps on Steroids. SiteMap and Form customization management is built on top of the CRM 2011 solution infrastructure.
One of the customer feedbacks with the current SiteMap and Form customization import/export feature is that whenever a new customization is imported, it wipes out previous customization. With CRM 2011, customizations from multiple imported (installed) solutions will be merged together and presented to the end user in a unified customization layer. This is made possible in part due to the design of the internal storage of SiteMap and Form customization, which is the topic of this blog.
Unmanaged Solution
Unmanaged solution deals with the active customization layer. SiteMap and Form customization storage format in unmanaged solution is basically the same as before. I will not spend more time on it than point out the following bullet points:
- The full content of the SiteMap definition (SiteMapXml) and full content of the Form definition (FormXml) is included in the customizations.xml file that is zipped into the unmanaged solution zip file.
- SiteMap definition is included as ImportExportXml-> SiteMap xml node and complies with the schema defined at <CRM Server InstallDir>\Server\ApplicationFiles\SiteMapType.xsd.
- Form definition is included as ImportExportXml -> Entities -> Entity -> FormXml xml node and complies with the schema defined at <CRM Server InstallDir>\Server\ApplicationFiles\FormXml.xsd.
Managed Solution
Here is where the major storage format change has happened since CRM V4. The main idea here is to capture SiteMap and Form customization as a diff between customized SiteMap and Form and the base upon which the customization is made. And this diff is transported in the managed solution package and applied to end user SiteMap and Form base when the solution is installed at the end user deployment.
Please note, as the end user SiteMap and Form base at installation is quite likely different from the SiteMap and Form base upon which the customization is based, some issues can happen and workaround is needed. But that is for another discussion.
SiteMap customization is captured as ImportExportXml-> SiteMap xml node in the customizations.xml file that is zipped into the managed solution zip file and complies with the schema defined at <CRM Server InstallDir>\Server\ApplicationFiles\SiteMapTypeManaged.xsd. If there is no SiteMap customization, this node does not exist in the solution customizations.xml file.
Form customization is captured as ImportExportXml -> Entities -> Entity -> FormXml xml node in the customizations.xml file that is zipped into the managed solution zip file and complies with the schema defined at <CRM Server InstallDir>\Server\ApplicationFiles\FormXmlManaged.xsd. If there is no form customization for a particular form, this node does not exist in the solution customizations.xml file for that form.
If you compare SiteMapTypeManaged.xsd to SiteMapType.xsd or FormXmlManaged.xsd to FormXml.xsd, you will notice that the main difference is that the xml definition for many elements in the managed version has an additional attribute named solutionaction with the following valid values:
<xs:simpleType name=“solutionactionType“> <xs:restriction base=“xs:string“> <xs:enumeration value=“Added“ /> <xs:enumeration value=“Removed“ /> <xs:enumeration value=“Modified“ /> </xs:restriction> </xs:simpleType >
“Added” is used to indicate that this element (and all its child elements) is added by the customization. “Removed” is used to indicate that this element (and all its child elements) is deleted by the customization. And “Modified” means some aspect of this element (not considering its child elements) is modified by the customization. If an element is not affected by the customization, solutionaction attribute will not appear in its definition of xml node. And if an element and all its child elements are not affected by the customization, the xml node sub tree will not appear in the solution customizations.xml file.
Some Sample Illustrations
Since the managed solution packaging for SiteMap customization and Form customization is similar and uses the same engine, I will be using SiteMap customization to illustrate the internal storage of customization in a managed solution.
I made some changes to the out of box SiteMap under SiteMap -> Area (Id=”Workplace”) -> Group (Id=”MyWork”) node:
- I changed the Icon for the nav_dashboards SubArea from /_imgs/area/18_home.gif to /_imgs/data_management.gif.
- I added a new node <SubArea Id=”link” Title=”link” … >
- And I deleted the node of <SubArea Id=”nav_calendar” …>
See the following screen shots:
And when I include the SiteMap in a solution for Export as Managed Solution, I see the following in the ImportExportXml-> SiteMap xml node in the customizations.xml file that is zipped into the managed solution zip file:
<SiteMap> <SiteMap> <Area Id=“Workplace“ …=“” > <Group Id=“MyWork“ …=“” > <SubArea Id=“nav_dashboards“ …=“” Icon=“/_imgs/data_management.gif“ …=“” solutionaction=“Modified“ /> <SubArea Id=“nav_activities“ …=“” /> <SubArea Id=“nav_calendar“ solutionaction=“Removed“ /> <SubArea Id=“link“ Title=“link“ …=“” solutionaction=“Added“ /> </Group> </Area> </SiteMap> </SiteMap>
“…” above means some detail is not shown.
As you can see that the nav_dashboards SubArea node has solutionaction=”Modified”, the nav_calendar SubArea node has solutionaction=”Removed”, the link SubArea node has solutionaction=”Added”, and the nav_activities SubArea node does not have solutionaction attribute. That is how the customization is captured and stored in the managed solution for transport to the end users.
Conclusion
There you have it about the internal storage of SiteMap and Form customization in a managed solution package. I hope I have achieved my goals for this blog:
- To satisfy any curiosity about the internal storage of SiteMap and Form customization in a managed solution package of CRM 2011.
- To equip you with knowledge to help you debug issues with SiteMap and Form customization during solution import and export. During export, you can verify if all your customization is captured in the exported solution. And during import, you can identify certain cases of import failure and help you to find workarounds if necessary.
Please take a note that the manual editing of managed solution files is not supported (at your own risk) and the information presented here is accurate as of the CRM 2011 Beta release. I hope you benefit from the improvements we made in this area and let us know what can be further improved for future releases. Thank you for choosing Microsoft Dynamics CRM.
