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.ContextualTabsin 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.AddExistingAssocCommand=Mscrm.AddExistingRecordFromSubGridAssociatedSequence=40LabelText=$Resources(EntityDisplayName):Ribbon.SubGrid.AddExistingAlt=$Resources(EntityDisplayName):Ribbon.SubGrid.AddExistingImage16by16=/_imgs/ribbon/AddExistingStandard_16.pngImage32by32=/_imgs/ribbon/AddExistingStandard_32.pngTemplateAlias=o1ToolTipTitle=$Resources(EntityDisplayName):Mscrm_SubGrid_EntityLogicalName_MainTab_Management_AddExistingAssoc_ToolTipTitleToolTipDescription=$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=40LabelText=$Resources(EntityDisplayName):Ribbon.SubGrid.AddExistingAlt=$Resources(EntityDisplayName):Ribbon.SubGrid.AddExistingImage16by16=/_imgs/ribbon/AddExistingStandard_16.pngImage32by32=/_imgs/ribbon/AddExistingStandard_32.pngTemplateAlias=o1ToolTipTitle=$Resources(EntityDisplayName):Mscrm_SubGrid_EntityLogicalName_MainTab_Management_AddExistingAssoc_ToolTipTitleToolTipDescription=$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

Advertisements

6 thoughts on “Walkthrough – Adding CustomRule to OutofBox Ribbon Button

  1. I want to hide the quote form report button based on the field value but as you mentioned that I didn’t found the button for report button in list of Quoteribbon xml file in SDK.

    Please suggest me how I can do it for Quote report button

    1. Hi Rajesh,
      As I understand you are looking for hiding “Run Report” button on Form. If this is the case you have to look for following XML Element in “quoteribbon.xml”

      HTH

  2. Hello, nice article. I have changed all the ribbon buttons to create account (I have redirected to my own web to create account) except the lookup in contact. Can I change “New” the button in the account’s lookup window within contact entity ? thanks in advance.

    Furqan

    1. Hi Furqan,
      Button in Lookup up window does not come under Ribbon, so we cannot make changes to that button using Ribbon Customization. I am not aware of any other way of customizing buttons in Lookup window. Can you let me know what is purpose of customizing New button in Account Lookup?

      1. Thanks for the quick reply. Actually I am calling my web which is calling some web service and then creating the account entity, so for making it consistent I need all the places where I can create account I need to call my web instead of default entity form. Anyhow I have implemented unsupported way and changed the lookup page of CRM Dynamics and disabled New button whenever the lookup is for objecttype == account. if you find any better way please let me know. Cheers, Furqan

  3. Great article, really helped me out. The only suggestion I feel would make this whole process clearer, is have a a final RibbonDiffXml pasted at the end, showing what the final product is.

    You can also add in that inside of the MSCRM-SDK\resources\exportedribbonxml you can find all the ‘default’ XML’s, such as the contact xml.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s