Building Custom Screens using Dialogs and Ribbon Buttons in CRM 2011

In this post I demonstrate how you can rapidly extend Microsoft CRM with custom screens in minutes, rather than hours or days. 

I will demonstrate a custom Lead Qualification screen by using a custom Ribbon button that pops a CRM Dialog and I will share a couple of tweaks that smarten up the user experience.

---

Microsoft have supplied with Microsoft CRM 2011 a Lead Qualification screen where you can qualify or disqualify a Lead and chose what records you want created:

However, this screen sits outside CRM’s supported extensibility model and sometimes fails to meet requirements. When you hit this scenario you can attempt an unsupported customisation to the screen, you can build a replacement screen, you can use form fields and plug-ins to manage the requirement or you can use a Dialog.  In this post I will demonstrate the Dialog solution and provide some guidance on how you can improve the user experience.

Here’s my scenario.  I have Leads for both existing Customers (Contacts) and for non-customers.  I want users to be able to qualify or disqualify leads.  When they qualify them I want the system to create an Opportunity against a Contact record.  For non-customer Leads, the Contact record should be auto-created.

In this scenario the out-of-the-box screen has these limitations:

• The user can choose to have a new Account created (I never want this)
• The user can chose to have a new Contact created, even when the Lead references an existing Contact (we could end up with duplicates)
• The user can accidentally chose to not have an Opportunity created
• The user has to reselect the Contact on this form if they wish to associate the Opportunity to an existing Contact (despite the Contact being referenced on the Lead)

Ok, so let’s jump to the solution so you can see whether you like this approach.   I have added a Button to the Lead form’s ribbon menu which pops a Dialog:

If the user selects “Convert Lead” an Opportunity is created, the Lead status is updated and the Lead form is refreshed.  If the Lead referenced an existing Contact then the Opportunity will be attached to that Contact, otherwise a new Contact is created.  

If the user select “Disqualify Lead” the Dialog will prompt them for a reason and then update and close the Lead and refresh the Lead form.

The advantage with this approach is it is a more controlled user experience.  We are not exposing the user to options we don’t want them to select and not asking them to perform any double keying.   And by creating a ribbon button and adding some jscript to auto-refresh the CRM form we get a much nicer user experience then an out-of-the-box  Dialog experience.

Here’s how I configured this…

 

The Dialog

 

The Dialog is quite simple.  It has 2 pages.  The 1st page you see in the screenshot above.  It asks a question and captures the response.   You’ll see from the Dialog definition below that I then have a condition statement and only proceed to the 2nd page if the user chose the  “Disqualify” option on the 1st page:

Next, the Dialog needs to take action.  

For Disqualified Leads, the Dialog updates the Status of the Lead based on the Disqualify Reason captured:

For Qualified Leads, the Dialog checks whether the Lead references an existing customer and then either just creates an Opportunity record or creates a Contact and an Opportunity, before finally closing the Lead:

 

The Button

 

I added the Ribbon button using the VisualRibbonEditor available on CodePlex.  I copied the icon path and display rule from the out-of-the-box Qualify button.  Here’s the Action definition for the button:

            <Actions>
               <JavaScriptFunction FunctionName="LaunchDialog" Library="$WebResource:new_LaunchDialog">
                <CrmParameter Value="PrimaryItemIds"/>
              </JavaScriptFunction>
            </Actions>

I needed to pass the Lead record’s GUID to my function so you will see I registered a CrmParameter in my ribbon definition.  “PrimaryItemIds” will give you the GUID of the current record.

 

The Jscript

 

Here’s my LaunchDialog function that the button calls.  There’s also a supporting function which just ensures the Dialog launches centred on screen:

function LaunchDialog(sLeadID) {
    var DialogGUID = "128CEEDC-2763-4FA9-AB89-35BBB7D5517D";

    // Get the CRM URL 
    var serverUrl = Xrm.Page.context.getServerUrl();

    // Cater for URL differences between onpremise and online 
    if (serverUrl.match(/\/$/)) {
        serverUrl = serverUrl.substring(0, serverUrl.length - 1);
    }

    serverUrl = serverUrl + "/cs/dialog/rundialog.aspx?DialogId=" + "{" + DialogGUID + "}" + "&EntityName=lead&ObjectId=" + sLeadID;
    PopupCenter(serverUrl, "mywindow", 400, 400);
    window.location.reload(true);
}

function PopupCenter(pageURL, title, w, h) {
    var left = (screen.width / 2) - (w / 2);
    var top = (screen.height / 2) - (h / 2);
    var targetWin = window.showModalDialog(pageURL, title, 'toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=' + w + ', height=' + h + ', top=' + top + ', left=' + left);
} 

This function receives the Lead record’s GUID as a parameter (thanks to the ribbon definition) and combines that with the CRM Server URL (which is derived via Xrm.Page.context) and with the GUID of the Dialog definition (which is hardcoded) and then pops that URL.  It uses window.showModalDialog() and window.location.reload(true) to automatically refresh the Lead form when the Dialog closes.

Now I have hardcoded the GUID of the Dialog in my function.   A better solution would be to have that housed as a parameter and read at runtime.  Check out this post for an approach you can follow to implement that.

That’s it, I hope someone finds this useful.

GT.