Opening URL Addressable Forms to Create new Related Records

Since the beginning of time CRM has had URL addressable forms.  This features makes it possible to consistently open an existing CRM entity form from script or from other programs simply by passing a series of mysterious URL parameters to the CRM website.  And that is the key – those pesky and mysterious URL parameters.  For simple use cases, the parameters are actually pretty well documented in the CRM SDK. 

The purpose of this post is to show how to pass parameters when you want a button on a parent form that will open a new related record form.  This seems like it would be a common use case, but I found it hard to find any really clear example of how to do this.  A few articles here and here were helpful but I still spent over an hour trying to work this out for myself.  So in the interest of supporting the community and perhaps saving others an hour or more trying to figure this out on their own, I thought that I’d blog it. 

My use case is pretty simple.  I want a button called Check-In on the Contact Form (see fig.1).  When I click the button, it will open a new custom entity (called rmtc_monthlyclubbookresponse) form with the related contact already filled in (see fig.2). 

Figure 1 – Check-in button on the form.

Figure 2 – Create new related entity form.

The first step to create this is to add the button to the Contact form.  I prefer to use the Visual Ribbon Editor tool that you can pick up on Codeplex.  My approach is to have the button call a webresource javascript script that will open a new browser window, passing the correct parameters.  In the visual editor I added an action for my button to call my javascript webresource (see fig.3).  I reference my webresource library as:

$webresource:rmtc_/Scripts/toolbarCommands

Figure 3. – Visual Ribbon Editor reference to script webresource.

Now for the tricky part – the code to set the correct parameters and to open a new IE window with the related entity form.  I will show you the finished code, and not bore you with the details of how I got it (it is probably what you want anyhow).   

    1:  function Checkin() {

    2:      var serverUrl;

    3:      var errorMessage = "Context is not available.";

    4:      var context;

    5:      if (typeof GetGlobalContext != "undefined") {

    6:          context = GetGlobalContext();

    7:      }

    8:      else {

    9:          if (typeof Xrm != "undefined") {

   10:              context = Xrm.Page.context;

   11:          }

   12:          else {

   13:              alert(errorMessage);

   14:              return;

   15:          }

   16:      }

   17:      var entityId = context.getQueryStringParameters().id

   18:      var entityEtc = context.getQueryStringParameters().etc

   19:      var serverUrl = context.getServerUrl();

   20:   

   21:      if (serverUrl.match(/\/$/)) { serverUrl = serverUrl.substring(0, serverUrl.length - 1); }

   22:      var recordUrl = serverUrl + "/main.aspx?";

   23:      var params = "etn=rmtc_monthlyclubbookresponse";

   24:      params += "&pagetype=entityrecord";

   25:      params += "&extraqs=" + encodeURIComponent("?_CreateFromId=" + entityId + "&_CreateFromType=" + entityEtc) 

   26:      var URL = recordUrl + params; 

   27:      window.open(URL, "_blank", "width=900px,height=600px,resizable=1");

   28:   

   29:  }

Please note that I liberally borrowed pieces of this code from other places.  The key item to look at is line 25.  CRM supports a URL parameter called extraqs.  This is used to pass custom parameters to forms.  It turns out that there are two sub-parameters, _CreateFromId  and _CreateFromType that can be use to pass the related record information into the new entity form.  You will note that the underscore is required.  Also note that you must URI Encode the parameters and that it begins with a required question mark “?”. 

The _CreateFromId parameter is the entity ID of the contact record in my case.  It is easily picked up from the context.  The _CreateFromType is the entity type code of the parent entity, which is contact in my case.  Hardcode that at your own risk, as these type codes will change from one organization to another.  To do it right, I also pick up the ETC from the query string in the context. 

The final stage is to cruft up the URL line 26 and call Window.Open passing in our new URL.  CRM takes it from there, opening the related entity form and pre-filling the lookup field of the contact entity (figure 2). You can see the parameters passed to your form in the IE address bar by pressing CTRL-N.  

Hopefully this is going to save you some time trying to decipher these query string parameters on your own.  As always, please leave me feedback if I missed something or if this helped you.