Walkthrough – Adding CustomRule to OutofBox Ribbon Button

CRM 2011 has introduced Ribbon. Few weeks back I spent some time to customize Ribbon button and add CustomRule which Enables and Disables Ribbon Button based on JavaScript function return value.
I thought of sharing my experience so that others can take advantage of my learning.

Functionality Required:

I have Many-To-Many relationships between Contact and Account entity, on Account form there is Navigation Link for Contacts which enables user to Add Existing Contacts to Account. These Contacts can be seen by any user who has Read permission on Account and Contact, but we need to implement extra check to allow only certain Users to Add Existing Contacts based on certain logic driven on values of certain attributes of Account entity. So
when User opens Account Form and click on Contact Link either in left Navigation Pane or click on Contact Sub-Grid on Account for, CustomRule should get fired and depending upon output of Rule “Add Existing Contact” button in Ribbon should be enabled or disabled.

Following are steps which need to carry out

1. We first need to take Contact Ribbon XML.The definitions of the default ribbon definitions are included in the downloadable files in the Microsoft Dynamics CRM SDK. The SDK\SampleCode\CS\Client\Ribbon\ExportRibbonXml\ExportedRibbonXml folder includes the output files you would have for an organization with a ribbon that has not been customized. You don’t need to run the sample application to export this data. If you have a customized ribbon, you should run the sample application to refresh the files in this folder with any customizations previously applied for your organization. File name for Contact should be contactribbon.xml

2. Open contactribbon.xml in MS VS 2010. Since we have to apply rule for Contact Ribbon in Account form, locate
<ContextualGroupId=“Mscrm.SubGrid.contact.ContextualTabs” in contactribbon.xml,

It will list various Buttons, for our purpose we need following button which is shown in Associated View of Contact.

<ButtonId=“Mscrm.SubGrid.contact.AddExistingAssoc” Command=“Mscrm.AddExistingRecordFromSubGridAssociated” Sequence=“40” LabelText=“$Resources(EntityDisplayName):Ribbon.SubGrid.AddExisting” Alt=“$Resources(EntityDisplayName):Ribbon.SubGrid.AddExisting” Image16by16=“/_imgs/ribbon/AddExistingStandard_16.png” Image32by32=“/_imgs/ribbon/AddExistingStandard_32.png” TemplateAlias=“o1” ToolTipTitle=“$Resources(EntityDisplayName):Mscrm_SubGrid_EntityLogicalName_MainTab_Management_AddExistingAssoc_ToolTipTitle” ToolTipDescription=“$Resources(EntityDisplayName):Mscrm_SubGrid_EntityLogicalName_MainTab_Management_AddExistingAssoc_ToolTipDescription“/>

In this button there is Command property which gets called everytime button is loaded in UI, CRM has default Commands for Out Of Box Ribbon Buttons. In same contactribbon.xml locate CommandDefinition with Id as Mscrm.AddExistingRecordFromSubGridAssociated, it should look like

<CommandDefinitionId=“Mscrm.AddExistingRecordFromSubGridAssociated“>
<EnableRules>
<EnableRuleId=“Mscrm.AppendToPrimary“/> <EnableRuleId=“Mscrm.EntityFormIsEnabled“/> </EnableRules>
<DisplayRules><DisplayRuleId=“Mscrm.AddExisting“/>
<DisplayRuleId=“Mscrm.ShowForManyToManyGrids“/>
<DisplayRuleId=“Mscrm.AppendToPrimary“/>
<DisplayRuleId=“Mscrm.AppendSelected“/>
</DisplayRules>
<Actions>
<JavaScriptFunction FunctionName=“Mscrm.GridRibbonActions.addExistingFromSubGridAssociated“
Library=“/_static/_common/scripts/RibbonActions.js“>
<CrmParameterValue=“SelectedEntityTypeCode“/>
<CrmParameterValue=“SelectedControl“/></JavaScriptFunction>
</Actions>
</CommandDefinition>

Thats all information we need from contactribbon.xml file

2. Now create a new Solution and add Contact entity to it. Export the solution and open solution zip file and open customizations.xml in MS VS 2010.

3. In customizations.xml, there should be <RibbonDiffXml> in it, all the Ribbon Customization goes under this element. If there is no prior customization don on contact Ribbon it should look like

<RibbonDiffXml>
<CustomActions>
</CustomActions>
<Templates>
<RibbonTemplatesId=“Mscrm.Templates“></RibbonTemplates>
</Templates>

<CommandDefinitions>
</CommandDefinitions>

<RuleDefinitions>
<TabDisplayRules />
<DisplayRules />
<EnableRules/>
</RuleDefinitions>

<LocLabels/>
</RibbonDiffXml>

4. Copy the CommandDefinition we found in contactribbon.xml (with Id = Mscrm.AddExistingRecordFromSubGridAssociated) and paste it in Customizations.xml file under <CommandDefinitions> tag. Once copy give new Unique Id to CommandDefintion in customizations.xml

<CommandDefinition Id=”Mscrm.AddExistingRecordFromSubGridAssociated_CustomAction“>

5. Since we have to enable and disable Ribbon button we have add new <EnableRule>. Add this rule under <RuleDefinitions>. Again give new Unique Id to this rule. You can have Rule depending upon your requirement, in my case I have CustomRule which calls JavaScript function.

<EnableRule Id=”Mscrm.AddExistingRecordFromSubGridAssociated_CustomRule“>

<CustomRule FunctionName=”isUserPartnerTeamMember” Default=”false”

Library=”$webresource:mbs_/UserSettings.js”>

6. Once created Refer this EnableRule in Command Definition

<EnableRule Id=”Mscrm.EntityFormIsEnabled” />

7. Now we all set with CommandDefinition. We have to add Button element copied from contactribbon.xml under <CustomActions> tag in customization.xml. Important thing to note here is Location property of CustomAction should be exactly same as ButtonId and Command property of Button should now refer to new Id of CommandDefinition which we have created in above steps.

<CustomActions>
<CustomActionId=“Mscrm.SubGrid.contact.AddExistingAssoc_CustomAction“  Location=“Mscrm.SubGrid.contact.AddExistingAssoc“  Sequence=“40“>
<CommandUIDefinition>
<ButtonId=“Mscrm.SubGrid.contact.AddExistingAssoc”  Command=“Mscrm.AddExistingRecordFromSubGridAssociated_CustomAction“  Sequence=“40” LabelText=“$Resources(EntityDisplayName):Ribbon.SubGrid.AddExisting” Alt=“$Resources(EntityDisplayName):Ribbon.SubGrid.AddExisting” Image16by16=“/_imgs/ribbon/AddExistingStandard_16.png” Image32by32=“/_imgs/ribbon/AddExistingStandard_32.png” TemplateAlias=“o1” ToolTipTitle=“$Resources(EntityDisplayName):Mscrm_SubGrid_EntityLogicalName_MainTab_Management_AddExistingAssoc_ToolTipTitle” ToolTipDescription=“$Resources(EntityDisplayName):Mscrm_SubGrid_EntityLogicalName_MainTab_Management_AddExistingAssoc_ToolTipDescription“/>
</CommandUIDefinition>
</CustomAction>
</CustomActions>

8. Finally import customization back in CRM and new CustomRules should be effective.

Hope this helps