Introducing Xrm.Panel for Microsoft Dynamics 365

Dominic Jarvis, 28 February 2018

Panels are a convenient feature introduced as a preview feature in the December 2016 update for Dynamics 365 (see: https://msdn.microsoft.com/en-us/library/mt790281.aspx ). Although technically available, the functionality didn’t appear to do anything until version 9 (tested with v8.2 on-premise).

The feature is still in preview, but does provide access to some helpful capabilities. It is important to note that as the feature is still in preview Microsoft does provide a disclaimer that the feature is not meant for production use, and the current API reference is woefully lacking. You can find the documentation for this here: https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/clientapi/reference/xrm-panel

What It Does

The panel API provides a method to display a web page in the side pane of the Customer Engagement form. Think of it as an iFrame that is accessible from most locations in the Dynamics 365 system. The main place that we want to be using it however is on entity forms.

Figure 1: Displaying the Panel from a Dashboard

Usage

The panel is opened and closed using the Xrm.Panel.loadPanel(url, title) method.

In order to load the panel, simply call the loadPanel function with a url like so:

Xrm.Panel.loadPanel("https://www.bing.com");

This will load the target web page into the panel. To close the panel, simply call the loadPanel function with a blank URL. Note that this is not a null URL, but an empty string.

Xrm.Panel.loadPanel("");

It is also possible to load Web Resources into the panel, which can provide another handy place to display custom functionality.

I have created a simple web resource here which has been loaded into the panel using the web resource URL.

Xrm.Panel.loadPanel(Xrm.Utility.getGlobalContext().getClientUrl() + "/WebResources/new_/html/helloPanel.html");

Results in:

Limitations

The target web page must allow being displayed in an iFrame. This means that while http://www.bing.com may be displayed, https://www.google.com may not be.

There is no direct access to the Xrm object from within the Panel frame, so any web resources loaded into the Panel will need to manually navigate to a frame on the page that does have access to the Xrm object in order to use those methods, or add a reference to ClientGlobalContext.js.aspx from inside your web resource.