Adding a new Button Group to the CRM Ribbon

Here’s a quick run through on how to add a new Group of buttons to the ribbon in Microsoft CRM 2011.

Here’s the end result that will be achieved:


In this scenario we are customising the Phone Call entity’s Form ribbon.  In particular the Main Tab of that ribbon (the tab that carries the name of the Entity).

To implement this change we need to customise the Phone Call entity.  At present CRM does not provide a UI for Ribbon customisations but the customisation XML does support these changes.  So we need the Phone Call entity’s customization xml.   Create a Solution, add the Phone Call entity, export the solution, unzip and then open the customization.xml file in Visual Studio.

Collapse the EntityInfo and FormXml nodes and you should see the RibbonDiffXml node, this is where we specify changes to the Ribbon.  Replace the CustomActions line with the following XML:

  <CustomAction Id="Mscrm.Form.phonecall.CustomGroup.CustomAction" 
      <Group Id="Mscrm.Form.phonecall.CustomGroup.Group" 
              Title="Gareths Group" 
        <Controls Id="Mscrm.Form.phonecall.CustomGroup.Controls"> 
          <Button Id="Mscrm.Form.phonecall.CustomGroup.Button.A" 
                  LabelText="Button 1" 
                  Image32by32="/_imgs/ribbon/newchart32.png"  /> 
          <Button Id="Mscrm.Form.phonecall.CustomGroup.Button.B" 
                  LabelText="Button 2" 
                  Image32by32="/_imgs/ribbon/CustomEntity_32.png"   /> 
  <CustomAction Id="Mscrm.Form.phonecall.CustomGroup.MaxSize.CustomAction" 
      <MaxSize  Id="Mscrm.Form.phonecall.CustomGroup.MaxSize" 
                Size="LargeLarge" /> 
  <CustomAction Id="Mscrm.Form.phonecall.CustomGroup.Popup.CustomAction" 
      <Scale    Id="Mscrm.Form.phonecall.CustomGroup.Popup.1" 
                Size="Popup" /> 

We are adding 3 Custom Actions here: 

  • The first Custom Action adds the new Group and the 2 Buttons inside that Group.
  • The second Custom Action adds the MaxSize definition for the Group to the Scaling definition of the Ribbon.  This tells CRM how to display the buttons when the screen size does not require any collapsing of the buttons.
  • The third Custom Action adds the Scale definition for the Group to the Scaling definition of the Ribbon. This tells CRM how to display the buttons when the screen size is insufficient.

To adjust my sample code for your scenario do the following:

Do a Find and Replace on “phonecall”, replacing with the name of your entity.

Change the Location value on line 3 to the relevant Group ID of your entity’s Ribbon definition.  I’ll explain.  In my scenario I wanted to add a Button Group to the Phone Call form’s Main tab so I went and found the Phone Call ribbon definition in the SDK here:


[UPDATE: 14 Dec 2011 – The latest SDK did not include the ribbon definition XML files forcing you to build and run an app from source code provided in order to generate them for your self. I provide instructions on this process here]

And looked for my Tab in that file, finding it here (see the yellow highlight below):


I wanted to add a new Group under the Groups section of the Ribbon so the Location value in our customization file needs to be that Groups Id (highlighted in green above) – appended with ._children.  i.e.:


That’s all you need to change at this stage.  We’ll come back and personalise other settings in a sec, let’s just try and get the button group to appear first.

Ok, now we need to add some commands to our customization file.  Replace the CommandDefinitions line with the following XML:

  <CommandDefinition Id="Mscrm.Form.phonecall.CustomGroup.Button.A.Command"> 
    <EnableRules /> 
    <DisplayRules /> 
      <Url Address="" /> 
  <CommandDefinition Id="Mscrm.Form.phonecall.CustomGroup.Button.B.Command"> 
    <EnableRules /> 
    <DisplayRules /> 
      <Url Address="" /> 
  <CommandDefinition Id="Mscrm.Form.phonecall.CustomGroup.Command"> 
      <EnableRule Id="Mscrm.ConvertActivity" /> 
      <DisplayRule Id="Mscrm.ConvertActivity" /> 
    <Actions /> 

Here again we have 3 bits, 3 Command Definition’s:

  • The first Command Definition defines what should happen when the first button is clicked.  I just have a hardcoded URL being launched. 
  • The second Command Definition defines the 2nd button’s action.
  • And the third Command Definition defines when the Group of buttons should be enabled and visible.  You can alternatively set these rules per button.  You’ll see I am referring to a rule called “Mscrm.ConvertActivity”.   I got this from the phonecallribbon.xml.  This is the rule used for the Convert to Case button.  I find it’s handy to just steal the rule of another button who’s behaviour you want to mimic.

To adjust my sample code for your scenario do the following:

Change the URL being launched by each button or replace s jscript function call like the below:


And find a Display Rule and Enable Rule in your entity’s ribbon.xml that you can use.  You can’t just use my “Mscrm.ConvertActivity” rule as it may not exist on your entity.

Ok, that should be enough to get our buttons to appear.  To deploy, zip back up the customization.xml file along with it’s other solution files and then import that solution zip file back into CRM and Publish.  Pop your form and you should now see the new Button group and it’s 2 buttons:


To adjust the appearance you can now go back and tweak some of the XML attributes (after which you would re-zip, import and publish).

To change where the Group appears on the Ribbon change the Sequence value under the Group node:


Refer back to the entity’s ribbon.xml to see what sequence each existing Group has to figure out what value you need to slot your in between:


Change the Button Group label and the label of the individual buttons here:


Change the Button icon here:


You have 2 approaches for setting the button icons.  You can browse the entity’s ribbon.xml (or any entity’s ribbon.xml for that matter, or even applicationribbon.xml) and steal the path and filename of a button you want to use.   Or, you can upload your own button icons as web resources and then reference the web resource, which is done in this manner:


That should be enough to get you going.  Hope this helps someone.



15 thoughts on “Adding a new Button Group to the CRM Ribbon

  1. JJ


    would you know how to ‘permanently’ group button within particular group? I added quite a number of buttons for my entity, but they show up depending on user screen resolution. Possibly the best would be groups “grouped” at all times and have buttons available within pop up. I played with ‘MaxSize’ but with no success yet.


  2. Tanguy

    Hi Gareth,

    thank you for this post which is really helpfull.
    But I am trying to implement your solution (on a custom entity called new_reglements) and I have a problem. I do not understand the display rule point.
    I well notice that I need to replace the DisplayRuleId by one of my entity display rules. I did not find any DisplayRuleId on the customizations.xml (from my solution). So I tried to use one DisplayRule from the new_reglementsribbon.xml. But when I try to import my solution I have this error :

    L’élément du ruban “Mscrm.Form.new_reglements.CustomGroup.Command” est dépendant de

    In english it means that The ribbon element Mscrm.Form.new_reglements.CustomGroup.Command is dependent on .

    I do not understand this error.

    Could you give me a hand?

    Best Regards


  3. crm_dev

    Hi Gareth,
    Thank you for the post, it’s REALLY helpful!
    What I like to know is how can I use your method to do the below:
    1- I have an IFrame on my form displaying a default website intially
    2- when a certain button from the ribbon is clicked, I want to change the source of the IFrame, pass parameters to it(which am gonna read form the form) and refresh the IFrame.

    Is it feasible?
    Thanks in advance!

    1. Gareth Tucker Post author

      Hi, yes very feasible. Put the logic into a jscript function and upload as a web resource. Have your button action call that function. That function will read values from the CRM form, concatenate into a URL and then you would do a setsrc to change the iframe URL. Check my jscript reference post for some of this and google “CRM setsrc iframe” for the rest.

  4. Pingback: How To Trigger a Plug-in From JScript in Microsoft Dynamics CRM - Jamie Miley - Life and Technology - CRM Technical Blogs - Microsoft Dynamics Community

  5. pinu

    i am facing a starnge issue , i have added 2 buttons to a custom grou. the issue is that the java script that i have called in the command defination of the first button not being called, instaed the second button jS is getting executed. i have throughly checked that my command iD are different for both the buttons. can any one help me to this .


Leave a Reply

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

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

Google photo

You are commenting using your Google 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 )

Connecting to %s