When to edit the customizations file

Applies to Dynamics 365 (online), version 9.x

The customizations.xml file that is exported as part of an unmanaged solution can be edited to perform specific customization tasks. After editing the file you can compress the modified file together with the other files exported in the unmanaged solution. You apply the changes by importing that modified unmanaged solution.

Editing a complex XML file like the customizations.xml file is much easier and less prone to errors if you use a program designed to support schema validation. While it is possible to edit this file using a simple text editor like Notepad, this is not recommended unless you are very familiar with editing this file. For more information, see Edit the Customizations file with Schema Validation.

Important

Invalid XML or incorrect definition of solution components can cause errors that will prevent importing a manually edited unmanaged solution.

Supported tasks

You can edit the customization.xml file to perform the following tasks.

Editing the ribbon
This documentation describes the process of editing the ribbon by editing the customization.xml file directly. Several people have created ribbon editors that provide a user interface to make editing the ribbon easier. The most popular one so far is the Ribbon Workbench. For support using this program, contact the program publisher.

For more information about editing the ribbon by editing the customization.xml manually, see Customize the Ribbon for Microsoft Dynamics 365.

Editing the SiteMap
The SDK describes the process of editing the SiteMap by editing the customization.xml file directly. However, its recommended that you use the site map designer in Customer Engagement to create or update site maps. More information: Create a site map for an app using the site map designer

You can also use one of the community-developed site map editors, such as the XrmToolBox Site Map Editor.

For more information, see Change Application Navigation using the SiteMap

Editing FormXml
FormXml is used to define entity forms and dashboards. The form editor and dashboard designer in the application are the most commonly used tools for this purpose. Editing the customizations.xml file is an alternative method. For more information, see Customize Entity Forms in Microsoft Dynamics 365 and Create a Dashboard.

Editing saved queries
Definitions of views for entities are included in the customizations.xml file and may be manually edited. The view editor in the application is the most commonly used tool for this purpose. Editing customizations.xml is an alternative method. For more information, see Customize Entity Views in Microsoft Dynamics 365.

Editing the ISV.config
In earlier versions of Dynamics 365 Customer Engagement, ISV.Config was the way to add client application extensions as well as some other configuration options. For Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online, the Ribbon provides the way to extend the application. The only remaining capability left in ISV.Config is to customize the appearance of the Service Calendar. For more information, see Service Calendar Appearance Configuration.

Unsupported tasks

Defining any other solution components by editing the exported customizations.xml file is not supported. This includes the following:

  • Entities

  • Attributes

  • Entity Relationships

  • Entity Messages

  • Option Sets

  • Web Resources

  • Processes (Workflows)

  • Plugin Assemblies

  • SDK Message Processing steps

  • Service Endpoints

  • Reports

  • Connection Roles

  • Article Templates

  • Contract Templates

  • E-mail Templates

  • Mail Merge Templates

  • Security Roles

  • Field Security Profiles

See also

Customize Microsoft Dynamics 365 and Microsoft Dynamics 365 (online)
Customization XML Reference
Customization Solutions File Schema
Ribbon core schema Ribbon types schema Ribbon WSS schema
SiteMap schema
Form XML schema
Schema Support for the Customization File