Monday, September 22, 2014

Running a Report from a Ribbon Button

Here’s a quick walk-through on running a report directly from a ribbon button, this set up will save users a couple clicks so they don't have to navigate to the list of reports and pick the one they want to run. It makes even more sense if you only have a single report related to the record or it's used frequently. In this example I’ll show how to run a report from the Order entity form. I’ll be showing this using CRM 2013 but it should work equally well in CRM 2011.

First off, if you haven’t already downloaded and installed Scott Durrow's Ribbon Workbench solution go ahead and do that now.

Next you’ll need to create a solution that contains all the items we’ll need so that Ribbon Workbench can work its magic. Add the existing Order entity, if prompted you won’t need to add the dependent components. If you want your button to have images associated with it, add them at this time too. Finally add a new JavaScript web resource file, we’ll worry about the contents in a bit.


Now we’ll need to find out a couple pieces of information about the report that needs to be opened. Navigate to the Order entity and run the report. Take note of the URL in the report viewer, it should look something like this:

Specifically note the items I’ve bolded, these are the report name, report unique identifier, and the entity type code of of the main entity.

Once we have this information we can add the code to our new JavaScript web resource. You can cut and paste this code to start and then substitute your values in place.

function OpenOrderReport() {
    var rdlName = "Order.rdl"; //Replace
    var reportGuid = "8500df62-a624-e411-8882-6c3be5a8ea94"; //Replace
    var entityType = "1088"; //Replace
    var entityGuid =;  
    var url = Xrm.Page.context.getClientUrl() + "/crmreports/viewer/viewer.aspx?action=run&context=records&helpID=" + rdlName + "&id={" + reportGuid + "}&records=" + entityGuid + "&recordstype=" + entityType;, null, 800, 600, true, false, null);

If you decide to change the name of the function that’s OK just remember what you changed it to as we’re going to need that later. It's also probably a good idea at his point to export the new solution. Just in case you make a mistake you'll be able to re-import it and start over.

Now head over to Settings –> Solutions and open the Ribbon Workbench solution. You should be prompted to choose a solution to work with, as you’d guess you’ll want to use the solution you just created.

Once open, the first step will be to add a new button to the command bar on the form. Make sure your entity is selected from the list (in this case is shows up as 'salesorder') and then click Button in the toolbox area and drag it onto the command bar in the position you want it displayed in. Make sure you are placing it on the bottom most set of icons and this represents the form while the others represent the commands associated with a main view or associated view/sub-grid. Also for CRM 2013 users I'd suggest placing closer to the left hand side so it shows up on the screen in the first 5-7 items so users don't have to go to the overflow menu to find it - the goal here is to reduce clicks after all. FYI it might be a bit tricky to position the button just where you want it when getting it in-between others.


Once placed, click on the new button and then look to the properties area on the right hand side of the page. If you are going to want images associated with your button, use the lookup icon to select to appropriately sized icons that you included in the solution earlier. At this time complete the different label fields that control the different facets on the button text being displayed.


The JavaScript we are going to apply to this button needs the record id as one of the parameters to open the report. When you are first creating a new Order CRM won't generate a record id until after the initial save. So prior the the first save if we ran that script it would fail because the record id wouldn't yet exist. To prevent this we'll add an enable rule to the button so it doesn't show up until after the record has been saved the first time.

To do this, right click on Enable Rules and then select Add New. You should now be able to expand the list of rules and see the one it just created. Once you select it I'd suggest changing the name to something a bit more descriptive as the generic name that gets generate by default won't mean much if you do other ribbon work later and have other enable rules. Now you can right click on the rule that you just created and select Add Rule. From the pop-up choose Form State Rule. Expand the tree further under the new rule to select the FormStateRule. Then set InvertResult to True and State equal to Create. Essentially what is happening is when the ribbon gets loaded CRM will evaluate the form state to see if it's a new record. If it is indeed a new record it would return a positive result and show the button. But in our case we don't want the button to be shown on new records so that's why we set the InvertResult option to True. That way on new records it would return a negative result and not display the button. To explain a bit differently, if an enable or display rule returns a positive or True value the button would be enabled or displayed. If it returns a negative or False value the button would be disabled or hidden. It is also worth pointing out the in CRM 2013 enable and display rules both actually end up hiding the item. In CRM 2011 an enable rule would show the button a greyed out but in CRM 2013 they've decided to just save the screen space and not display it at all.

So now to get a button to do something when clicked we'll need to create a command. So right click on Commands and select Add New. Once again expand and rename the new command. Next select the lookup by Actions and in the resulting pop-up select Add and then JavaScript Function Action. From the resulting screen use the lookup by Library to choose the JavaScript web resource you added to the solution and then enter the FunctionName from the script (the example uses OpenOrderReport).


To make sure the button isn't displayed on new records we'll need to add the enable rule we created by using the lookup by EnableRules and choosing it from the list.


Almost done, now we just need to tie the command to the button. So get back to your button and select the new command from the list.


At this point before committing the changes select the Xml tab and hit the little refresh icon. This will show all the xml that this wonderful tool just generated for you. You'll want to then check the Messages tab as it will contain any warnings or errors. You'll want to resolve any errors displayed before publishing.


When you are ready use the Publish button at the top of the page to deploy your changes, it can take a little while so be patient.

Once it completes you should be able to navigate to an Order record and refresh the page to see the new button. Clicking it should open the order report directly.