Customization concepts
Applies To: Dynamics CRM 2013
Of course you’re eager to get started, but please take a few minutes to read the content in this section. This will introduce you to important terms, give you some background about why things are done a certain way, and help you avoid potential problems in the future.
In This Topic
What is metadata and why should you care?
What kinds of customizations are supported?
What kinds of customizations are not supported?
What you need to know about solutions
Publishing customizations
What is metadata and why should you care?
In the past, you customized business applications by editing the source code. This created a mess because each organization had unique changes and it was impossible, or extremely expensive, to upgrade. Then, application developers started exposing application programming interfaces (APIs) so that other developers could interact with the application and add their own logic without touching the source code. This was moderately better because it means developers can extend the application without changing it. But it still requires a developer to write code.
Today, modern business applications use a metadata-driven architecture so that people can customize the application without writing code. Metadata means “data about data” and it defines the structure of the data stored in the system. With this metadata, an application knows about any changes to the data structure and this enables the application to adapt as the data structure changes. Since the metadata is known, additional capabilities can be included that are tied to the metadata.
When you customize Microsoft Dynamics CRM using the customization tools in the application, you’re adding or updating the metadata or data used by features that depend on the metadata. Because we know the kinds of data used to customize the system, we can take this data into account and add new features to CRM without breaking your system. This way you should always be able to apply an update rollup or upgrade to the latest version and enjoy the best new features.
Customize or Configure?
Most people say that they want to customize the application, so we use the word “customize” to describe changing the system to make it work the way you want. Some people prefer to use the word “configure” because it suggests that no code was required to make changes. Call it whatever you like, we just want to make it clear that you don’t need to be a developer to customize Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online.
Microsoft Dynamics CRM provides a set of web services and APIs that allow developers to write code. When code is written using supported methods you can expect that it will continue to work when you upgrade your organization.
What kinds of customizations are supported?
We expect that you can do most of your customization with the tools in the application. Everything you do by using those tools is supported by Microsoft because they apply changes to the metadata or data that depends on the metadata.
But, if the customization tools don’t meet your needs, you can install a solution provided by a third party or hire a developer to code your customizations. Either way, it’s good for you to understand supported customizations. If you need to invest in a solution that requires code, you should make sure that the code is written using only supported APIs. This helps you protect your investment in both CRM and any solutions you get.
Developers who extend Microsoft Dynamics CRM have a responsibility to follow rules and best practices documented in the SDK. Download the Microsoft Dynamics CRM SDK package. The SDK documents the APIs available to developers and provides guidance about how to best use them. Microsoft supports the APIs and practices that are documented in the SDK. APIs and programming practices not documented in the SDK are not supported by Microsoft. You may find something on the internet that describes how you can solve a problem, but if it doesn’t leverage APIs documented in the SDK, it is not supported. Before you have a developer apply a change you should verify whether it uses supported methods.
If developers use the APIs and best practices described in the SDK we can be sure to test whether any of the changes we make to CRM has the potential to break existing customizations. Our goal is that code customizations written using supported methods will continue to work when new versions or updates of CRM are released over time. You benefit because you can upgrade to new versions with improved features without having developers change their code each time.
If we detect that a change in a new version of CRM will cause a supported customization to break, we will document what will break and how people can change their code to fix it.
What kinds of customizations are not supported?
Just because certain APIs and programming practices are not supported by Microsoft doesn’t mean that they don’t work. “Unsupported by Microsoft” means exactly what it says: you can’t get support about these APIs or programming practices from Microsoft. We don’t test them and we don’t know if something we change will break them. We can’t predict what will happen if someone changes code in our application.
The developer who uses unsupported APIs and programming practices assumes the responsibility to support their code. They will need to test their code to make sure it works.
If you choose to use unsupported customizations in your CRM deployment you should be sure to document what was done and have a strategy to remove those customizations before you contact Microsoft Dynamics CRM Technical Support. If you need help with unsupported customizations, contact the developer or organization who prepared the customizations.
Common unsupported customization practices
The following is a list of common customization practices that are not supported. This is not a complete list. For more information see the SDK topic Supported Extensions for Microsoft Dynamics CRM : Unsupported Customizations
Interacting with the web application Document Object Model (DOM) elements using JavaScript
Any JavaScript libraries used anywhere in the application must only interact with the documented APIs. When JavaScript developers work with applications they frequently access DOM elements using specific names. Because Microsoft Dynamics CRM is a web application these techniques work, but they are likely to break during an update rollup or upgrade because the names of the elements they reference are subject to change at any time. We reserve the right to make any changes necessary in the application and this frequently means changing how the page is constructed. Adding any changes that depend on the current structure of the page means that you will need to invest in testing and perhaps changing the custom code in these scripts each time you apply an update rollup or upgrade your application.jQuery is a very common library used by JavaScript developers. Most of the benefit of using jQuery is that it simplifies a developer’s ability to access and create DOM elements, which is exactly what we do not support in the CRM application pages. jQuery is recommended when developers are creating custom user interfaces with HTML web resources, but within the CRM application pages, the supported APIs do not require jQuery to be used.
Using any undocumented internal objects or methods using JavaScript
Microsoft Dynamics CRM uses many JavaScript objects within pages. A JavaScript developer can discover these objects by debugging a page and then access and reuse these objects. We reserve the right to make any changes necessary to these objects, including removing them or changing the names of the methods. If a script references these objects the script will break if they are not found.Directly changing files in the application
If you have Microsoft Dynamics CRM 2013 on-premises you have access to the web application installed on your server. The web application contains many text files that a developer could edit or replace to change the behavior or appearance of the application. Changing these files is not supported because any update rollup that you install could remove your changes and the files will be overwritten when you upgrade to the next release.Retrieving data directly from database tables
If you have Microsoft Dynamics CRM 2013 on-premises you have access to the database so that you could retrieve data directly from the tables. However, by doing this you are by-passing the security infrastructure. The recommended practice is to use special filtered views to retrieve the data. This will apply the calling user’s security so that they can only see data that they should see.Updating data directly in the database tables
If you have Microsoft Dynamics CRM 2013 on-premises you can perform updates on the CRM data directly in the database tables. The risk with this approach is that you can set invalid data that can break the application. Developers should always use the APIs provided with the application platform web services to update data.Changing the database tables, stored procedures, or views
If you have Microsoft Dynamics CRM 2013 on-premises you can use database tools to change the database. The only direct database changes that are supported are adding or updating indexes as described in Custom SQL Server indexes. You should use the customization tools to add any new entities or entity attributes. This is the only supported way to apply changes to these parts of the database. Any direct changes you make risk breaking the application or your ability to apply update rollups. Any changes you apply may be destroyed when you apply an update or during an upgrade and any data that you may have included in custom database table columns will be lost.
What you need to know about solutions
Solutions exist so that a set of customizations can be purchased, shared or otherwise transported from one organization to another. You can get solutions in the Microsoft Dynamics Marketplace or from an independent software vendor (ISV). A CRM solution is a file that you can import to apply a set of customizations.
Note
If you are an ISV creating a customization that you will distribute, you’ll need to use solutions. For more information about using solutions, see Package and Distribute Extensions.
If you are just interested in customizing your organization, here is what you need to know about solutions:
Creating solutions is optional. You can customize your CRM system directly without ever creating a solution.
When you customize the CRM system directly, you work with a special solution called the Default Solution. The Default Solution contains all the components in your system.
You can export your Default Solution to create a backup of the customizations you have defined in your organization. This is good to have in a worst case scenario.
Solution components
A solution component represents something that you can potentially customize. Anything that can be included within a solution is a solution component. The following is a list of solution components that you can view within a solution:
Application Ribbon
Article Template
Business Rule
Chart
Connection Role
Contract Template
Dashboard
Email Template
Entity
Entity Relationship
Field
Field Security Profile
Form
Mail Merge Template
Message
Option Set
Plug-in Assembly
Process
Sdk Message Processing Step
Security Role
Service Endpoint
Site Map
Web Resource
Most solution components are nested within other solution components. For example, an entity contains forms, views, charts, fields, entity relationships, messages and business rules. Each of those solution components requires an entity to exist. A Field can’t exist outside of an entity. We say that the Field is dependent on the Entity. There are actually twice as many types of solution components as shown in the list above, but most of them are not visible in the application.
The purpose of having solution components is to keep track of any limitations on what can be customized using Managed properties and all the Solution dependencies so that it can be exported, imported, and (in managed solutions) deleted without leaving anything behind.
Managed and unmanaged solutions
A managed solution can be uninstalled after it is imported. All the components of that solution are removed by uninstalling the solution.
When you import an unmanaged solution, you add all the components of that solution into your default solution. You can’t remove the components by uninstalling the solution.
When you import an unmanaged solution that contains solution components that you have already customized, your customizations will be overwritten by the customizations in the unmanaged solution. You can’t undo this.
Important
Install an unmanaged solution only if you want to add all the components to your default solution, and overwrite any existing customizations.
Even if you don’t plan on distributing your solution, you might want to create and use an unmanaged solution to have a separate view that only includes those parts of the application that you have customized. Whenever you customize something, just add it to the unmanaged solution that you created.
You can only export your Default Solution as an unmanaged solution.
To create a managed solution, you choose the managed solution option when you export the solution. If you create a managed solution, you can’t import it back into the same organization you used to create it. You can only import it into a different organization.
How solutions are applied
All solutions are evaluated as layers to determine what your CRM application will actually do. The following diagram shows how managed and unmanaged solutions are evaluated and how changes in them will appear in your organization.
.jpeg "Solution layering")
Starting from the bottom and working up to top:
System Solution
The system solution is like a managed solution that every organization has. The system solution is the definition of all the out-of-the box components in the system.Managed Solutions
Managed solutions can modify the system solution components and add new components. If multiple managed solutions are installed, the first one installed is below the managed solution installed later. This means that the second solution installed can customize the one installed before. When two managed solutions have conflicting definitions, the general rule is “Last one wins”. If you uninstall a managed solution, the managed solution below it takes effect. If you uninstall all managed solution, the default behavior defined within the System solution is applied.Unmanaged Customizations
Unmanaged customizations are any change you have made to your organization through an unmanaged solution. The system solution defines what you can or cannot customize by using Managed properties. Publishers of managed solutions have the same ability to limit your ability to customize solution components that they add in their solution. You can customize any of the solution components that do not have managed properties that prevent you from customization them.Application Behavior
This is what you actually see in your organization. The default system solution plus any managed solutions, plus any unmanaged customizations you have applied.
Managed properties
Some parts of Microsoft Dynamics CRM can’t be customized. These items in the system solution have metadata that prevents you from customizing them. These are called managed properties. The publisher of a managed solution can also set the managed properties to prevent you from customizing their solution in ways they do not want you to.
Solution dependencies
Because of the way that managed solutions are layered some managed solutions can be dependent on solution components in other managed solutions. Some solution publishers will take advantage of this to build solutions that modular. You may need to install a ‘base’ managed solution first and then you can install a second managed that will further customize the components in the base managed solution. The second managed solution depends on solution components that are part of the first solution.
CRM tracks these dependencies between solutions. If you try to install a solution that requires a base solution which is not installed, you will not be able to install the solution. You will get a message saying that the solution requires another solution to be installed first. Similarly, because of the dependencies, you cannot uninstall the base solution while a solution which depends on it is still installed. You have to uninstall the dependent solution before you can uninstall the base solution.
Solution publisher
Every solution has a Publisher. The default solution has a publisher named “Default Publisher for <your organization name>”.
The publisher record contains a Prefix value. The default value of this prefix is “new”. When you create new solution components this prefix will be appended to the name. This is a quick way that allows people to understand what solution the components are part of.
Before you start customizing the system we recommend that you change the Prefix value for the default publisher to something that identifies your company.
To change the Solution Publisher Prefix for the default publisher
Navigate to Settings > Customizations.
Select Publishers.
If there is more than one publisher, open the one with the Display Name that starts with Default Publisher for <your organization name>.
At the bottom of the form update the Prefix field to change the default value of ‘new’ to something that identifies your organization.
When you change the value, make sure to tab to the next field. The Option Value Prefix will automatically generate a number based on the customization prefix. This number is used when you add options to option sets and provides an indicator of which solution was used to add the option.
Publishing customizations
Certain customizations that make changes to the user interface require that they be published before people can use them in the application. Publishing provides a way for you to save your work before you have finished and then come back and finish at a later time. Publishing is only required when you change a solution component. When you create or delete a solution component publishing occurs automatically. Before you export a solution you will be prompted to publish customizations. This is because any unpublished customizations will not be included in the solution.
When you perform customizations that will appear in Microsoft Dynamics CRM for tablets you should always explicitly publish your customizations to make sure that every item is synchronized with the CRM for tablets application.
Note
Publishing customizations can interfere with normal system operation. In a production environment we recommend that you schedule publishing customizations when it’s least disruptive to users.
The following solution components require publishing when they are updated:
Application Ribbon
Entity
Entity Relationship
Field
Form
Message
Option Set
Site Map
Web Resource
See Also
Getting started with customization
Privileges required for customization
Use solutions for your customizations
© 2016 Microsoft Corporation. All rights reserved. Copyright