Exchanging data between CRM Forms and IFRAMEs

One of the most common requirements when we add content in IFRAMEs or Web Resourses in CRM is to have the ability to communicate with the calling or source CRM form to perform all sorts of operation. This article explains how this can be achieved using the postMessage JavaScript messaging mechanism.

What does postMessage do?

It’s a JavaScript method which was initially created to facilitate cross-origin communication between web pages. There are often valid scenario in which we need to display a page from another website in a new window or in an IFRAME. That’s the easy part. The more complicated part is when there is a requirement to perform some operations on the source page based on a action that occurs on the external page in the new window or IFRAME.

In the example below, consider we have a contact form that displays an external page in an IFRAME. When a button in clicked in the IFRAME, information (example, a lookup value) is passed to the CRM form, the value is set on the screen and the form is saved.

Step 1 – Write methods for the CRM Form: Register Listener, Message Handler  

The code below contains two methods, the first one (RegisterListener) sets a method that will be called if the postMessage is invoked (UpdateContactLookup). 


SADAX.Contact =
{
   RegisterListener: function () {

     if (window.addEventListener) {
       window.addEventListener('message', SADAX.Contact.UpdateContactLookup, false);
     }
     else { // IE8 or earlier
       window.attachEvent('onmessage', SADAX.Contact.UpdateContactLookup);
     }
   },

   UpdateContactLookup: function (event) {

     var origin = "";
     if (event.domain) origin = event.domain; // IE
     else if (event.origin) origin = event.origin; // FireFox - Chrome

     if ("https://source" == origin) {

       if (event.data != null) {

         var entity = SadaxJSON.parse(event.data);
         if (entity) {

           var value = new Array();
           value[0] = new Object();
           value[0].id = entity.Id;
           value[0].entityType = entity.LogicalName;

           var lookup = Xrm.Page.getAttribute("sadax_referencecontactid");
           lookup.setValue(value);
Xrm.Page.data.save();
}
}
else
{
alert("This message has been posted by an unknown source ('" + origin + "', expected 'https://source').");
return;
}
} 
}

Step 2 – Register the listener on Form’s OnLoad event

image

Step 3 – Write Code for the IFRAME to post the Message from the IFRAME

After the business logic execution, the postMessage method is called on the parent CRM form as follows:

function SetContactLookup(entityReference)
{
   var entity = {};
   entity.Id = entityReference.id;
   entity.LogicalName = entityReference.entityType;

   window.parent.postMessage(SadaxJSON.stringify(entity), "https://source");
}

Comments / Wrap up

At step 3, using the postMessage on the window.parent will cause the SADAX.Contact.UpdateContactLookup method to be fired on the parent CRM form. Notice that the method receives an event object as a parameter. The content of the object slightly differs based on the browser being used (IE vs rest of the world). Mostly, you should pay attention to the event.domain or event.origin attributes. This is used to validate the website that posted the message is safe (i.e. the one you are expecting).

There is also an event.data attribute that contains parameters that are sent from one page to another. In this case, we are using a renamed JSON library to stringify our custom object types. Passing an object without stringifying it would work, but we found it didn’t work well in all browsers/version. The reason for the renamed JSON library is again browser compatibility reasons. If IE8 is out of scope for you, you probably do not need this.

Notes:

  • This also work for web resources opened in a different window using window.open or Xrm.Utility.openWebResource
  • IE8 doesn’t allow to postMessage to other windows, only to iframes.
  • I haven’t tried this in CRM Online so you can try it by yourself if need be.

Custom User Interface in CRM – HTML5/JavaScript or ASP.NET Web application?

Lots of times on CRM projects, we are required to build and display custom screens inside of Dynamics CRM. There are a lot of factors that come into play in the choice how we build these custom user interfaces. It is a very key decision to make because it can sets the standard technologies and tools that you use for custom screens on project (among other things). I thought I’d share some key points to consider in your decision making process to determine what technologies and tools to use.

The need for custom user interface

First, it is important to know and understand when it is required to build custom UI as part of your CRM solution implementation. As a wrote a few years ago, we sometimes find ourselves in situations where we can come up with a complex data model and we feel like the out of the box UI capabilities won’t be user friendly enough to drive user adoption. Situations like that create the need to build more user friendly interfaces to simply make people’s lives easier when they start using the CRM/XRM application. Some examples are

  • Custom calendar view for timekeeping
  • Tree view to display a complex hierarchy
  • Interactive Bing or Google maps views of CRM data
  • Editable grids
  • Complex grids with aggregates, grouping functionalities
  • Integrated views to other systems

And the list goes on. The needs are very different depending on the nature of the enterprise looking to implement a CRM/XRM solution.

Most common technology choices

From experience, I have seen a lot of custom screens built using the following tools/technologies:

  • Silverlight
  • ASP.NET / ASP.NET MVC
  • HTML/HTML5 + JavaScript + CSS

The screens are usually displayed in web resources or in an IFRAMES inside CRM on forms or as standalone modules (open from a button, display in sitemap area). I will not cover Silverlight since Microsoft announced its end of life and continued support for a few additional years, plus the world has started to move on.

ASP.NET / ASP.NET MVC

  • Pros
    • Flexible server side business logic
    • Easily integration with external systems (web services, databases etc.)
    • Can be very quick to develop depending on the requirements, expertise and accelerators (advanced controls provided by Telerik, Infragistics or others can speed up development time significantly)
    • Develop with a familiar programming language (C# + Visual Studio) – this of course depends on your development background
  • Cons
    • Requires the deployment and maintenance of a hosted web application
    • You have to deal with the weight of ASP.NET (ViewState, Postbacks etc.)
    • Not a great fit with CRM Online and cloud offerings in general (cloud deployment, cross origin web sites, integrations etc)
    • Required additional configuration in CRM + JavaScript to set the IFRAME’s sources (URL)
    • Effort for developing custom web applications is often under-evaluated

HMTL(5)/JavaScript

  • Pros
    • Usually, a much lighter solution and if done properly, custom UI components can be very responsive and provide great user experience
    • All components are in CRM Web Resources (html pages, JavaScript files, images…)
    • Custom screens are CRM Solution aware and there is no need for deploying and maintaining an additional web site on a web server
    • A definite plus for cloud based Dynamics CRM implementations
    • Can be very quick to develop depending on the requirements, expertise and accelerators (Kendo UI controls or others can speed up development time significantly; other frameworks like Knockout JS, Bootstrap can also be useful)
    • Leverage trending technologies and tools
    • Use any IDE you want (no obligation to use Visual Studio, even if you should J)
  • Cons
    • Possibly additional complexity if you need to display information from an external system
    • If not structured properly, JavaScript code can become massive and hard to navigate/maintain
    • For non-web developers, might be a steep learning curve
    • Need to establish good project structure and standards (e.g. use TypeScript or Script Sharp)

What else to consider?

There are other factors to take into account, some being specific to each organization. A few examples:

  • What is the expertise or your resource pool?
  • Do we have people to build and maintain what we deploy?
  • Are we in CRM Online or planning to move to CRM online?
  • Are we, as a company, trying to get into HTML/JavaScript more?

This is good food for thoughts for starters. If you want more guidance, feel free to reach out to us.

CRM 2013 – Client API New Functionalities Recap

If you’ve been following, I had a series of Client API posts late last year. Below I have regrouped the new Client API functionality in a table for reference. This can become helpful especially if you are developing with the “old” CRM 2011 mindset to easily see what you can achieve differently and/or more efficiently in CRM 2013. Details on the new functionalities is available on the Microsoft Dynamics CRM YouTube video and in the CRM 2013 SDK.

Area

Method and Syntax

Description

Data

Xrm.Page.data.refresh(save).then(successCallback, errorCallback)

Asynchronously refreshes and optionally saves all the data of the form without reloading the page.

You can pass a callback method to execute on success or error

Data

Xrm.Page.data.save().then(successCallback, errorCallback)

See my blog post on this here

Data

Xrm.Page.data.getIsValid()

Returns a Boolean value indicating if the form can be saved or not

Data

Xrm.Page.data.setFormDirty()

Set the form as dirty

Entity

Xrm.Page.data.entity.getPrimaryAttributeValue()

Gets a string for the value of the primary attribute of the entity.

UI

Xrm.Page.ui.setFormNotification(message, level, uniqueId);

Xrm.Page.ui.clearFormNotification(uniqueId)

Use setFormNotification to display form level notifications and clearFormNotification to remove notifications. Gareth Tucker has a great article on these here.

Controls

Xrm.Page.getControl(fieldName).setNotification(message)

Xrm.Page.getControl(fieldName).clearNotification()

See article linked above for details. Notifications can be set at the field level

Number

Xrm.Page.getAttribute(fieldName).setPrecision(precision)

This method is used to override the field’s precision

Date

Xrm.Page.getControl(arg).setShowTime(bool)

Specify whether a date control should show the time portion of the date.

Date

Xrm.Page.getControl(arg).setIsAllDay(bool)

Specify whether a date control should set a value including the entire day.

Lookup

Xrm.Page.getControl(arg).addCustomFilter(filter, entityLogicaName)

Use add additional filters to the results displayed in the lookup. Each filter will be combined with any previously added filters as an ‘AND’ condition

The entity logical name is optional. If this is set the filter will only apply to that entity type. Otherwise it will apply to all types of entities returned.

Lookup

Xrm.Page.getControl(arg).addPreSearch(handler)

Use this method to apply changes to lookups based on values current just as the user is about to view results for the lookup.

The argument is a function that will be run just before the search to provide results for a lookup occurs. You can use this handler to call one of the other lookup control functions and improve the results to be displayed in the lookup.

Lookup

Xrm.Page.getControl(arg).removePreSearch(handler)

This API call is used to remove event handler functions that have previously been set for the PreSearch event (see above)

Context

Xrm.Page.context.getUserName()

Returns the name of the current user.

Context

Xrm.Page.context.client.getClient()

Xrm.Page.context.client.getClientState()

See my blog post about it here

Utility

Xrm.Utility.alertDialog(message,onCloseCallback)

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

Displays a dialog box containing an application-defined message.

Displays a confirmation dialog box that contains an optional message as well as OK and Cancel buttons.

See additional notes on this here.

Utility

Xrm.Utility.isActivityType(entityName)

Determine if an entity is an activity entity.

Utility

Xrm.Utility.openEntityForm(name,id,parameters)

Opens an entity form. Parameters are optional and used to pass the form ID, set default field values or pass custom query string parameters

Utility

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

Opens an HTML web resource.

CRM 2013 – Client API: Save Event Arguments

There are a few useful additions that have been added to the client API around the Save event. They are 3 methods that have been formally introduced:

getSaveMode: Returns a value indicating how the save event was initiated by the user.
isDefaultPrevented: Returns a value indicating whether the save event has been canceled because the preventDefault method was used in this event hander or a previous event handler.
preventDefault: Cancels the save operation, but all remaining handlers for the event will still be executed.

The key method is the getSaveMode function. Think about the new auto-save feature on updated forms. The getSaveMode function allow the javascript method executing on the Save event to know why/how the record is being saved. That gives you the flexibility as a developer to add some additional logic to handle your scenario… Below is the list of values returned by the getSaveMode function based on the entity type.

Entity Event Mode Value
All Save 1
All Save and Close 2
All Save and New 59
All AutoSave 70
Activities Save as Completed 58
All Deactivate 5
All Reactivate 6
User or Team owned entities Assign 47
Email (E-mail) Send 7
Lead Qualify 16
Lead Disqualify 15

This is fantastic as you can now write script to handle very specific scenario like an activity being resolved, a record being saved and closed, assigned and other cases. Below is a usage example in which we prevent the auto-save from happening as presented in the SDK documentation:

function preventAutoSave(econtext) {
   var eventArgs = econtext.getEventArgs();
   if (eventArgs.getSaveMode() == 70) {
      eventArgs.preventDefault();
   }
}

Cheers

CRM 2013 – Client API: Save & Refresh

I know these operations seem like very basic functionalities that have been around for a while. I wanted to point a specific new feature that comes with CRM 2013: the ability to run a callback method after a refresh or after a save triggered from a JavaScript method.

In the past, using the old Xrm.Page.data.entity.save method caused a refresh of the page which dismissed any code after the save in your script. Take this scenario for example…

  • You have button in your ribbon on an Account form
  • The button calls an external web service to update some of the account field values based on the account’s Primary Contact value which is on editable on the form
  • The web service only takes the account id as a parameter, it loads the records, reads it and takes action

With the old save method, you had to require that the user saves the account so that the value of Primary Contact is saved to the database, then click your button that will call the web service with account ID. Such a requirement certainly causes pain in user experience especially if there are a lot of situations where they need to hit save, wait for refresh and click another button.

With the new Save and Refresh, we now have the possibility to add callback methods:

Xrm.Page.data.refresh(save).then(successCallback, errorCallback);

// Parameters
// save => A Boolean value to indicate if data should be saved after it is refreshed.
// successCallback => A function to call when the operation succeed
// errorCallbak => A function to call when the operation fails. It gets called with 2 parameters (an error code and a localized error message)

Xrm.Page.data.save().then(successCallback, errorCallback);

// Parameters
// successCallback => A function to call when the operation succeed
// errorCallbak => A function to call when the operation fails. It gets called with 2 parameters (an error code and a localized error message)

Having had this problem in the past makes this one a good candidate for most exciting new client API feature for me 🙂

Cheers

CRM 2013 – Client API: Dialogs

CRM 2013 introduces a couple of client side dialog methods under the Xrm.Utility library. The goal is to remove the use of window.open and window.confirm and replaces them with alertDialog and confirmDialog and to support these alert messages in CRM for Tablets. Also, the key difference is that these methods will not block code until a user closes them. However, they contain a callback function parameter to indicate what code should be executed depending on the user’s response.

The Xrm.Utility.alertDialog(message,onCloseCallback) method displays a dialog box that contains a message passed as a parameter. Optionally, you can also execute another method (onCloseCallback) when the OK button is clicked.

var message = "Alert Dialog ! ";
 Xrm.Utility.alertDialog(message, onCloseCallback);
 

The Xrm.Utility.confirmDialog(message, yesCloseCallback, noCloseCallback) method displays a confirmation dialog box that contains an optional message and an OK and a Cancel button. A callback method can be set to run after each of the button is clicked.

var message = "Confirmation Dialog ! ";
 Xrm.Utility.confirmDialog(message, null, null);
 

Again in this case, the methods are only available for “Updated Entities”. You can see my previous post to get the list of entities on which this will not work.

Cheers

CRM 2013 – Client API: Client Methods

The CRM 2013 client API adds a few useful methods. Here I am going to focus on the context.Client methods : context.client.getClient() and context.client.getClientState. These methods are used to find out what kind of client is running and to get the information about it being online or offline. This is useful if you have scripts that you want to run when you are in the web application and nowhere else (not in Outlook client, not on Mobile client). As a consequence of this API change, the previous context.IsOutlookOnline and context.IsOutlookClient are now deprecated.

The getClient method returns the value Web (browser), Outlook (Outlook client) or Mobile (mobile app). The getClientState method returns Online or Offline, the latter applying only to the Outlook and Mobile clients. It’s also worth noting that these methods are only available for what Microsoft calls “Updated Entities”. In short, it’s the entities that have an updated interface (most key entities like Account, Case, Contact, basic activities like Phone Call, Tasks fit into that category). It also works on custom entities.

The entities that are not updated still use the “classic forms” and the Client methods are not supported on these. Here is the list of the entities with classic forms:

Address
Article
Article Comment
Bulk Delete Operation
Connection
Discount
Discount List
Document Location
Email Attachment
Follow
Goal
Goal Metric
Import Source File
Invoice Product
Order Product
Price List
Queue Item
Quote Product
Rollup Field
Rollup Query
Saved View
Service
Service Activity
SharePoint Site
Site
Territory
Unit
Unit Group

Making Cross Domain AJAX calls from CRM Form JScript

One of the cool things about JScript in CRM 2011 is that you can now use the jQuery $.ajax method to call, most notably the CRM REST endpoint. Now, one of the things that is sometimes required in customers’ solution is the ability to call other REST endpoints from a CRM form. An example of that use case would be to have a button that calls a web service in order to perform some sort of operation (e.g. modify your current record, or just send data over another systems for synchronization etc.) in a synchronous and interactive way. Another example would be to automatically fill fields on a form with information coming from another system (retrieve them via web service and set the values on the form). There are two main issues with doing that :

  • First, some browsers will simply not allow jQuery AJAX requests to run if they are made to a domain different than that of the running web application. The reason behind is that not all browsers can create XMLHttpRequest objects that have a withCredentials property. That is used to specify that we want to include the user credentials in a cross domain request. To always have that working, jQuery has the solution for us. Use the following statement in the code before making the AJAX call: jQuery.support.cors = true;
  • The other more complicated issue is that most browsers simply won’t allow JavaScript to make a cross domain request for security reasons. In most contexts, this sounds normal and reasonable.

Here are a few workarounds if you are facing the second issue.

  1. Try to transfer your logic to the server side. Can you do what you need by using a dialog or a workflow with a custom activity (server side code)? Can your logic be performed on a synchronous plugin (server side code)? If one of these solutions is acceptable, then this is what you should do.Applies to: CRM Online, On Premise, ADFS / IFD
  2. Use IIS URL Rewrite rules on your server. To illustrate, let’s say your CRM server URL is http://MyCrmServer/MyOrg and your external REST endpoint is http://RestEndpoint/RestService?params. You can create a URL rewrite rule that will transform all requests coming in as http://MyCrmServer/RESTENDPOINT/RestService?params to http://RestEndpoint/RestService?params. In other words, whenever IIS sees the string MyCrmServer/RESTENDPOINT in a URL it replaces it with RestEndpoint. It is simple to configure with Regular Expressions.

    This is a good solution because it handles the request on the server side. From a Jscript perspective, it is as if you are querying the CRM server and the request is transformed once it reaches the server. You can read more about IIS URL Rewrite here. The downside of this approach is that every single page that is opened from the CRM web app triggers a URL rewrite rule evaluation. Microsoft says the algorithm are optimized for performance and I have never experienced visible delays due to using the rewriter. Also worth noting that obviously, this is not supported for CRM Online since we don’t have access to Microsoft’s CRM Servers.

    Applies to: CRM On Premise, ADFS / IFD (if provider gives access to CRM Server)

  3. Enable Cross Domain browsing on the browser. In IE, this is blocked by default. You can change the settings by going to Internet Options Security and Custom Level Settings. In most case, this solution is not acceptable for an enterprise’s perspective for security reasons.


    Applies to: CRM On Premise, ADFS / IFD, (CRM Online? Not confirmed but it should work)

I personally think making requests to a cross domain web site via JavaScript should not be done if there are acceptable other options simply because it adds overhead somewhere based on the solution you go with. (e.g. if you go with solution 2 on premises, you have to make sure all your CRM servers have rewrite rules create and enable etc.).

[*** Update | 13/06/2014 ***] If you are using CRM 2013, see this article on how to use Action processes to get around this challenge.

Hope this helps!

Passing Query String Parameters to Navigation Link URL

I was recently asked by a client to have a custom .NET page displayed on an entity form. Because of the content of the page (it’s a heavy, long and large!), we were all in agreement that using an IFRAME or a web resource in a Tab or Section on the main form was not going to be pretty. The best user experience is to have the page displayed when users click on a navigation link on the left menu.

Sounds easy, right? Not so fast! In our case, the custom web page displays content that is specific to the record it’s opened from. That means the page needs to know the ID of the record. That sounds easy as well, right? You are thinking simply pass the record ID as parameter in the query string… Yes, it works with an IFRAME and for a Web Resource, you can change the URL programmatically when the form loads or when a field value is changed. For a Navigation Link, not so fast! There is no supported way to change the URL programmatically!

This had me do some research to see what we could do to get around that limitation. Unfortunately, it has to be a non-supported approach.

You could attach to the On Click event of the navigation link or set the URL on load of the form. Regardless, problem is accessing the IFRAME in which your page resides. There are a few ways to do this as you can see here and here. I prefer solution 1 because you use the ID of the navigation URL (it is transported as part of the CRM solution and remains the same in all environments).


Alternatively, you could do it the other way around, meaning accessing the Xrm.Page.data.entity object from the web page in the IFRAME. This is done easily in JavaScript using something like window.parent.Xrm.Page.data.entity.attributes.get(“…”).getValue();. This is also not supported since we have no control over what the parent of the IFRAME window can become.

I want to say I hope Microsoft adds this functionality in a future update but with the new process driven UI forms that are coming in the Orion release, I don’t know if all this will still be relevant in a near future. We’ll see!

Creating a Loading Panel in Dynamics CRM Forms

On many occasions, I had to create ribbon button to perform business logic that sometimes takes time to complete and/or execute. One of the comment that I always get in these situations is that it’s annoying from an end user’s perspective not to know what is happening. This is true, the UI kind of freezes for a few seconds and then everything comes back to normal, users are never sure what to do during this time and it sometimes results on them trying to refresh the page or click on the button multiple times. Here I am sharing one way to build a modal loading panel on top of a CRM form that I use very often. It’s a fairly simple thing to do if you are opened to using jQuery.

The idea is to use jQuery to add a hidden HTML block (the loading panel) to the CRM form, this is done in the function called InitializeLoadingPanel. Then you add 2 methods, one to show the HTML block and another one to hide it. You can refer to the Jscript code below for the 3 functions.

function InitializeLoadingPanel() {

    if ($("body").find("#panel").length > 0) {
        return;
    }

    var displayText = "Working...";

    // Loading Panel
    $('body').append('<div id="panel"></div>');

    // Loading Panel Content Div
    $('body').append('<div id="contentDiv"></div>');

    $("#panel").hide()
               .css({ 'position': 'absolute', 'top': '0', 'left': '0', 'width': '100%', 'height': '100%', 'background-color': '#FFFFFF' });

     $("#contentDiv").append('<p id="loadingText">' + displayText + '</p>')
                    .hide()
                    .css({ 'background-color': '#DDDDDD', 'height': '100px', 'width': '300px' });

    // Setup your text css
    $("#loadingText").css({ "text-align": "center", "margin-top": "50px", "font": "12px bold" });

}

// Open the Loading Panel
function OpenLoadingPanel(callback) {

    // Make sure you Initialize the loading panel
    if ($("body").find("#panel").length <= 0) {
        InitializeLoadingPanel();
    }

    var panel = $("#panel");
    var panelContent = $("#contentDiv");
    var pageHeight = $(document).height();
    var pageWidth = $(window).width();

    panelContent.css("position", "absolute");
    panelContent.css("top", ((pageHeight - panelContent.outerHeight()) / 2) + $(document).scrollTop() + "px");
    panelContent.css("left", ((pageWidth - panelContent.outerWidth()) / 2) + $(window).scrollLeft() + "px");

    panel.css({ "z-index": 1000 });
    panelContent.css("z-index", 1001);

    if (callback != null) {
        panel.fadeTo("fast", 0.8, function () {
            panelContent.fadeIn(10, function () {
                setTimeout(callback, 10);
            });
        });
    }
    else {
        panel.fadeTo("fast", 0.8, function () {
            panelContent.fadeIn(10);
        });
    }
}

// Close the Loading Panel by hiding it
function CloseLoadingPanel() {

    $("#contentDiv").fadeOut("fast", function () {
        $("#panel").fadeOut(0, function () {
            ("#contentDiv").hide();
            });
    });
}

That’s good for starters. Now in order to test this, I have written a very simple function that simple opens the loading panel and sleeps for a few seconds in order for us to see the loading panel on the screen.

// In this example, I call this method on the OnChange event of a custom field in order
// to display the loading panel. In the past, I've had to use this in different cases
// from ribbon button to on change of field value. It really depends on what you are doing in your
// Javascript code.
function DisplayLoadingPanel() {

    OpenLoadingPanel();
    window.setTimeout(CloseLoadingPanel, 6000);
}

And now let’s take a look at the result. As I am mentioning in the comments on the code block above, in this example I set the DisplayLoadingPanel method to be called on the On Change event of a field on my form. Typically, you can have the loading panel displayed whenever you need. Here is what it looks like:

You can play around with the css to add an image to the loading block and do all sorts of things with the look and feel. This is all supported in theory (my example is running in CRM Online). Note that in order for this to work, you need to have a Jscript web resource with jQuery registered in the form before the script in which the loading panel is initialized, displayed and hidden.

Hope this helps!