I love Dynamics CRM dialogs. In fact, I think they are one of the best features of CRM 2011. What I don't like about dialogs is how the user has to run them when working with a entity record. On a "classic" mode form, the user has to go to the ribbon, click start dialog and then find the dialog in a list. If there are lots of dialogs for that entity type, the user then has to spend a lot of time looking, change the view or search. That experience is still better than on an "updated" mode forms where the user can't run dialogs at all without switching to classic mode. It is possible to launch a dialog via a URL from a web resource embedded in a CRM form using the format described here, but that approach requires you hardcode the GUID for the dialog you want to open. In this post I will show how to create a web resource dialog "launcher" that you can embed in a CRM form (both classic and updated modes) with JavaScript and an OData query.

Originally when I started looking at this, I was thinking about just a single dialog launch button, but then I remembered the "macros" system I created originally for CRM 3, and I realized that a dynamic dialog menu would achieve a lot of the same goals without anywhere near as much custom code. That being said, the approach I am going to show will allow you to create a menu that displays either a single dialog or multiple dialogs depending on exactly how you want to make them available to your end users.

Retrieving the dialogs

First, we have to retrieve the dialogs. Normally, I am a big fan of using FetchXML for all my multi-record CRM data retrieval, but I decided to get the list of dialogs via OData because the query is extremely simple, and I doubt anyone will run into a situation where the number of dialogs to retrieve will exceed the OData maximum limit.

Here is an OData query for retrieving an account-related dialog named Lucas Demo Account Dialog:

/WorkflowSet?$filter=Category/Value eq 1 and Type/Value eq 1 and StatusCode/Value eq 2 and PrimaryEntity eq 'account' and Name eq 'Lucas Demo Account Dialog' &$select=Name, WorkflowId, Description, Category, Type, PrimaryEntity&$orderby=Name

Let's take a closer look at the query parameters.

1. The workflow set contains workflows and dialogs, so we use Category/Value eq 1 to get only dialogs.
2. In addition to containing workflow and dialog definitions (and templates), the workflow set contains a separate entry for each activation. That is if you create and activate a dialog, then deactivate / edit / reactivate, etc., you will see the same dialog name multiple times in the results. This is why we use Type/Value eq 1 to get only the actual definition.
3. A user can't execute a draft dialog, so we use StatusCode/Value eq 2 to retrieve only published dialogs.
4. PrimaryEntity eq 'account' is used to retrieve only dialogs related to the account entity.
5. Name eq 'Lucas Demo Account Dialog' returns only dialogs with the name of Lucas Demo Account Dialog.

That query is fine if you only want users to be able to launch a single dialog from your menu, but what if you want to have multiple dialogs? The easiest way to do that is to remove the Name parameter, so a query for all account-related dialogs would look like this:

/WorkflowSet?$filter=Category/Value eq 1 and Type/Value eq 1 and StatusCode/Value eq 2 and PrimaryEntity eq 'account' & $select=Name, WorkflowId, Description, Category, Type, PrimaryEntity&$orderby=Name

This is OK, but there's a better approach that will allow for retrieving single or multiple records without having to use a different query format. Here's the query:

/WorkflowSet?$filter=Type/Value eq 1 and Category/Value eq 1 and StatusCode/Value eq 2 and PrimaryEntity eq 'account' and startswith(Name, 'XXX') &$select=Name, WorkflowId, Description, Category, Type, PrimaryEntity&$orderby=Name

Using the "startswith" operator gives you a lot more control. If you do startswith(Name, ''), you get everything. If you do startswith(Name, 'Lucas Demo Account Dialog'), you get just the single dialog (assuming you only have one dialog with that name/entity combination). This approach also allows you to show a subset of dialogs. Imagine you have two kinds of account dialogs, sales and service. If you prefix your sales dialogs with SALES- and your service dialogs with SVC-, you can filter the dialogs to build a service-only menu using the following query.

/WorkflowSet?$filter=Type/Value eq 1 and Category/Value eq 1 and StatusCode/Value eq 2 and PrimaryEntity eq 'account' and startswith(Name, 'SVC-')&$select=Name, WorkflowId, Description, Category, Type, PrimaryEntity&$orderby=Name

At this point, we have everything we need from an OData query perspective to write a separate web resource for every entity/functional combination, but I think it's better to use a generic web resource that takes the entity and name parameters via a query string. Unfortunately JavaScript doesn't have native query string parsing capability, so we need to use a custom function to extract the query string values. This is based on something I found on Stack Overflow.

function parseQueryString(qs) {  
var result = {}, keyValuePairs = qs.split('&');  
  
keyValuePairs.forEach(function(keyValuePair) {  
keyValuePair = keyValuePair.split('=');  
result[keyValuePair[0]] = keyValuePair[1] || '';  
});  
  
return result;  
}  
  
//For IE8- support include this tiny Array.forEach* polyfill:  
if ( !Array.prototype.forEach ) {  
Array.prototype.forEach = function(fn, scope) {  
for(var i = 0, len = this.length; i < len; ++i) {  
fn.call(scope, this[i], i, this);  
}  
}  
}

We then decode the querystring like this:

var queryObj = parseQueryString(location.search.slice(1));

Because we will be passing the dialog name and entity name to the web resource as custom parameter data, we have to URI decode the "data" object and then parse it. We can then pass the URI-decoded data object to the parseQueryString function to parse it like this:

var dataObj = parseQueryString(decodeURIComponent(queryObj["data"]));

With the query string fully parsed, here's the function to retrieve the list of dialogs.

function getDialogList() {  
var dialogname = dataObj["dialogname"];  
var entitytypename = dataObj["entitytypename"];   
  
//only execute query if the record already exists  
if((recordId != null) && (recordId != '')) {  
//set the path to the odata rest service  
//this can be hardcoded using the Organization Rest Service URL under Customizations->Developer Resources  
var odataPath = "https://" + window.location.host + "/XRMServices/2011/OrganizationData.svc";  
  
//no point inif entitytypename is provided  
if((entitytypename != null) && (entitytypename != ''))  
{  
//set up the odata query  
var retrieveReq = new XMLHttpRequest();  
var odataQuery = odataPath + "/WorkflowSet?$filter=Type/Value eq 1 and Category/Value eq 1 and StatusCode/Value eq 2";  
odataQuery += " and PrimaryEntity eq '"+entitytypename+"'";  
odataQuery += " and startswith(Name, '"+dialogname+"')";  
odataQuery += "&$select=Name, WorkflowId, Description, Category, Type, PrimaryEntity&$orderby=Name";  
retrieveReq.open("GET", odataQuery, false);  
  
//make sure we get json back  
retrieveReq.setRequestHeader("Accept", "application/json");  
retrieveReq.setRequestHeader("Content-Type", "application/json; charset=utf-8");  
  
//request/response will execute asynchronously, so we need a callback function  
retrieveReq.onreadystatechange = function () { generateLauncherMenu(this); };  
  
//send the request  
retrieveReq.send();  
}  
}  
}

Generating the launcher menu

Once the dialogs have been retrieved by the OData query, we can use jQuery to easily generate the contents of the launcher menu. There's lots of ways you can represent the dialogs to launch - buttons, hyperlinks, drop-down menu entries, etc. - but I think buttons are the best UI for a small set of dialogs.

The following function writes dialog-launching buttons to a div called launchDiv.

function generateLauncherMenu(retrieveReq) {  
//4 means a complete response  
if (retrieveReq.readyState == 4) {   
//parse response to json  
var retrieved = this.parent.JSON.parse(retrieveReq.responseText).d;   
  
for (var i = 0; i < retrieved.results.length; i++) {  
//create a button and append it to a launchdiv div  
var paramString = "\"" + retrieved.results[i].WorkflowId + "\",\"" + retrieved.results[i].PrimaryEntity+ "\",\"" +recordId + "\"";  
$('#launchDiv').append( "<button onclick='openDialog("+paramString+")'>Launch "+retrieved.results[i].Name+"</button><br />" );  
}  
};  
}

And then this function opens the dialog window:

function openDialog(processId, primaryEntity, entityId) {  
var url = "/cs/dialog/rundialog.aspx?DialogId=" + processId + "&EntityName=" + primaryEntity + "&ObjectId=" + entityId.replace('{','').replace('}','');  
window.open(parent.Xrm.Page.context.getClientUrl() + url);  
}

Putting it all together

Here's the complete web page you can upload as a web resource to your CRM system: dialog_launcher.htm (3.91 kb)

All you have to do is embed the web resource on your entity form and set the properties and custom parameter data like in the following image:

I have two account dialogs in my CRM system, Demo-Dialog #1 and Demo-Dialog #2. This is what the launcher menu looks like in a pre-Polaris, read-only form:

Here is what it looks like in a classic-mode form:

As always, happy coding!

One of the things I like best about the Dynamics CRM 2011 form object model is that it exposes the requiredlevel attribute for form fields, so you can dynamically set fields as required or not in response to user actions. This is great if you have different types of a single entity and business rules dictate that you must capture different data values for each type. For example, let's say you use the out-of-the-box Contact entity to represent two kinds of customers, small and large. For the small customers, your agents need to always fill in a customer loyalty code field, but for the large customers this field will never be populated. In the absence of a way to dynamically set the required level, you have two choices:

1. Make the field required at the Contact entity level and train your agents to type in something like "not applicable" or "N/A" for large customers. This, of course, fills up your database with garbage values.
2. Make the field optional, but train your agents to always populate it for small customers. This approach is even worse. While you can report on agent compliance retrospectively, you will almost assuredly end up with incomplete data for some records.

In this post, I will show how to use JavaScript to set the requiredlevel attribute of a field based on two separate conditions:

1. The value of another field on the form
2. The value of a field on a related entity (think a Contact's parent Account record)

Same-entity dynamic requiredlevel condition

The following method handles a silly scenario in which we need to check if a Contact's middlename field is populated, and if so, set the telephone1 field requiredlevel to required. If not, the requiredlevel of telephone1 will be set to none.

function SetRequiredSameEntity() {  
var middlename = Xrm.Page.getAttribute("middlename").getValue(); //get the middlename value  
if(middlename!=null)  
{  
Xrm.Page.getAttribute("telephone1").setRequiredLevel("required"); //set required  
}  
else  
{  
Xrm.Page.getAttribute("telephone1").setRequiredLevel("none"); //set none  
}  
}

To enable this functionality, do the following:

1. Create a new Jscript web resource that contains the SetRequredSameEntity method. I call mine, somewhat creatively I think, firstlibrary (new_firstlibrary).
2. Open the contact form designer.
3. Open the form properties.
4. Add the firstlibrary library to the form.
5. Add the SetRequiredSameEntity method to be called as part of the form OnLoad event. This is required so that the field is set to required if it already has a middlename populated when it loads. Make sure you enable the method, and you can, optionally, set dependencies so that the fields this method uses will not be removable from the form.
6. Close the form properties.
7. Double-click on the middlename field to open its property window. Go to the events tab and add the SetRequiredSameEntity method to be called as part of the field OnChange event just like in step 5.
8. Close the field properties.
9. Save your form changes and publish your customizations.
10. Open an existing contact record or create a new one to see the changes in action.

Related-entity dynamic requiredlevel condition

The following code handles a scenario in which telephone1 should be required for Contacts linked to a parent Account with an accountnumber value of 1234. Otherwise, telephone1 is not required. Unlike previously where the data was already available to us from the current form, in this method we will need to execute an OData query to retrieve the accountnumber value for evaluation.

function SetRequiredFromParentAccount() {  
//set the path to the odata rest service  
//this can be hardcoded using the Organization Rest Service URL under Customizations->Developer Resources  
var odataPath = "https://" + window.location.host + "/XRMServices/2011/OrganizationData.svc";  
  
//default telephone1 requiredlevel to "none"  
Xrm.Page.getAttribute("telephone1").setRequiredLevel("none");  
  
//get the parent account lookup  
var parentaccount = Xrm.Page.getAttribute("parentcustomerid").getValue();  
  
//if it's not null  
if(parentaccount != null)  
{  
//extract the id  
var parentaccountid = parentaccount[0].id;  
  
//set up the odata query  
var retrieveReq = new XMLHttpRequest();  
var odataQuery = odataPath + "/AccountSet?$select=AccountNumber&$filter=AccountId eq guid'" + parentaccountid + "'";  
retrieveReq.open("GET", odataQuery, false);  
  
//make sure we get json back  
retrieveReq.setRequestHeader("Accept", "application/json");  
retrieveReq.setRequestHeader("Content-Type", "application/json; charset=utf-8");  
  
//request/response will execute asynchronously, so we need a callback function  
retrieveReq.onreadystatechange = function () { SetRequired(this); };  
  
//send the request  
retrieveReq.send();  
}  
}  
  
//callback function to parse the response and react accordingly  
function SetRequired(retrieveReq) {  
//4 means a complete response  
if (retrieveReq.readyState == 4) {   
//parse response to json  
var retrieved = this.parent.JSON.parse(retrieveReq.responseText).d;   
  
//get the accountnumber value - CASE MATTERS!  
accountnumber = retrieved.results[0].AccountNumber;   
  
//if the accountnumber is 1234  
if(accountnumber=="1234")   
{  
//set the required level  
Xrm.Page.getAttribute("telephone1").setRequiredLevel("required");   
}  
};  
}

In this scenario we use two methods instead of one because the OData retrieve executes asynchronously, and we need a callback function to process the results whenever they come back. Beyond making sure you use the correct casing in your OData query and where you get the accountnumber out of the returned JSON object, it's basically standard JavaScript like before.

To enable this functionality, do the following:

1. Set the value of the odataPath variable to your Organization Rest Service URL under Customizations->Developer Resources.
2. Add these new methods to your script library.
3. Open the contact form designer.
4. Open the form properties.
5. Add the firstlibrary library to the form if it's not already there from the previous example.
6. Remove the SetRequiredSameEntity method to be called as part of the form OnLoad event, if it's already there. Add the SetRequiredFromParentAccount method to the form OnLoad event.
7. Close the form properties.
8. Double-click on the middlename field to open its property window. Go to the events tab and remove the SetRequiredSameEntity method if it's already there. Add the SetRequiredFromParentAccount just like before.
9. Close the field properties.
10. Save your form changes and publish your customizations.
11. Open an existing contact record or create a new one to see the changes in action.

Here is the code for the complete library: new_firstlibrary.js (2.02 kb)