Introduction
Most of my work is with SharePoint and SQL Server. However on a recent project I’ve been working with my ConcentrixTSG colleagues on a Dynamics CRM 2011 implementation. CRM 4.0 was a good product but they’ve certainly added and improved when they released 2011. On of the new features that mapped well to a customer process was Dialogs. Currently a prospect may phone up and our customer would talk them through the questions on a New Business Enquiry Form. These paper forms are then passed around several areas of the business and recorded on some Excel based registers. These registers are used for tracking and conversion analysis.
This seemed to map well to launching a dialogue that would provide the questions, record the answers and feed them into a new Lead record within CRM. There are two main issues with CRM to overcome:
- CRM 2011 Processes, whether workflows or dialogues, are still bound to an instance of an entity. So you must already have a Lead to run a dialogue to create a lead
- I wanted to be able to deliver a button on the ribbon that would launch the dialogue in a user friendly way.
It turns out that these two issues take a fair degree of effort to get around. Fortunately I found some help on the Internet. The articles that I mention here both helped me but I wanted to record my own experience as well. For my screenshots you’ll see that Lead has been renamed to New Business Enquiry.
Lead Creation Dialogue without a lead to run it against
The answer here to to run the dialogue off of an entity instance that you know will already exist, collect your answers and then use the dialogue to create a new lead. CRM Trick Bag gave me the answer here. When you create the Dialogue Process in CRM 2011 and you have to pick an entity, choose the User entity. The currently logged in user can always select their user record and press the Start Dialog button. They can then choose to launch the Lead Data Capture Dialogue, fill in the fields and on completion the dialog will create a new Lead based on the data captured.
For our Ribbon button we are going to put the URL required to call the dialogue directly onto the ribbon. We thus need to capture that URL somehow. Once your dialogue has been created and activated, select a user, press the Start Dialog button and choose your dialogue. On the Dialogue’s first screen that comes up press CTRL+N. This will launch a new screen. From this screen you can look at the URL and capture the GUID for the process. You’ll see this on the Trick Bag, you are looking for the first bit after %7b and up to %7d, these are the escaped versions of { and } used to surround a GUID. Copy that into a notepad window and keep it for later.
Add a button to the Ribbon
In CRM 4.0 this was a little bit tricky, in 2011 in much harder. Most of my guidance for this comes from CRM Mongrel so you’ll maybe want to look there as well. However the first thing you want to do is create some Web Resources so that the button will have something to do.
Create some Web Resources
Go into Settings/Customisations and open the default Solution or one of your own solutions, click into Web Resources and create a new Script file web resource. You can see that my function constructs a URL using Xrm.Page.context.getServerUrl() to find where you are and Xrm.Page.context.getUserId() to find who you are. The function then does a window.open to launch the dialog in a new window. This will pretty much work as-is in most situations as long as it has the correct URL that you got in the previous section.
Web Resource LaunchNBEF
The Web Resource editor. This one shows the function that launches the Dialog, GUID has been obscured but your GUID will be different to mine.
function callDialog() {
var url = Xrm.Page.context.getServerUrl();
url += "/cs/dialog/rundialog.aspx?DialogId=%7bED03DEEA-6AD6-4BE9-92C7-2C831071419D%7d&EntityName=systemuser&ObjectId=" + Xrm.Page.context.getUserId();
window.open(url, "", "status=no,scrollbars=no,toolbars=no,menubar=no,location=no");
}
For the time being, although the resource needs to have a function defined, it can just be a simple alert(“you pressed a button”). You can then get the button in and working before pasting in the correct function.
Our button is also going need an icon. for my example I reused the one from CRM Mongrel you need to add this as another web resource
Add the Ribbon Button
We are then going to edit the ribbon and
- Add a command that calls the function in our first web resource
- Add a button that has the picture from our second resources and when pressed calls the command
Buttons on the ribbon can only be added in valid places on the ribbon. In order to find a valid place you need to look at the SDK, find the ribbon for your entity and look what position numbers the existing buttons have been given. In the SDK you need to look in: \resources\exportedribbonxml\. You’ll find that there is a separate file with the ribbon xml for each of the built in ribbons. Open the one for the entity that you are interested in and look through it.
To put a button onto the main application you are going to be in the sections about: Mscrm.HomepageGrid. A Lead form would be: Mscrm.Form.lead.MainTab. The thing that you need to pay attention to is the Sequence numbers so that you can position your own button.
There are several ways to edit the actual ribbon, my approach was to use the Ribbon Editor for Microsoft Dynamics CRM from Codeplex. This doesn’t (or at least didn’t) work with Claims Auth enabled; my scenario was pre-live so I turned claims off for the work and back on after.
The first thing is to add a Command Definition to the Lead entity (renamed in this scenario).
I gave it one rule to always enable the button. This means that anyone who can get to Leads can press the button. This could be made more complex so that only people with rights to create Leads can have the button.
Then define the Action for the Command Definition that calls the function in the web resource that we defined earlier.
Having got the Command defined we can now add a Custom Action that will be represented by a new button:
The Location box has a text string that contains the information we read in the ribbon xml. In my example:
Mscrm.HomepageGrid.lead.MainTab.Workflow.Controls._children
We then need to define all the properties for the button
Sequence:60 – identifies the place we chose for our button in ribbonxml
Template:o1 – identifies a big square button
The rest is labels, image, tooltips and a pointer at the command we defined earlier.
CONCLUSION
There’s no getting away from it this is a long and complex process but I think the results of following it through create a good user experience for custom functionality.
