Building Business Processes in Dynamics CRM 2011: Installment 5

Calling Dialog Processes with a URL

Ultimately, what we want is something like a custom button on a ribbon which we can use to start a dialog process. But in order to address this topic properly, we need to take a step back and discuss a couple of slightly more fundamental topics first.

What Entity Should a Dialog be Written for?

Sometimes it’s obvious which entity a dialog should be written for, but just as with workflow processes, sometimes it’s not. Here are a couple examples of when it’s an easy decision:

• If you want an interactive process where a user selects a record and then makes a copy of it, changing a few values in the process, the dialog should be written for the record type you want to copy. Case to case, opportunity to opportunity, and so forth.
• Suppose you want to create an alternative to the standard lead qualification process. Since you’d want to start the process from the context of a selected lead record, create this dialog process for the lead entity.

On the other hand, consider the following business requirements:

You have a process that creates a case record, but part of the process is to gather some information and use it to search for an existing customer record. If it’s found, a case is created and associated with the customer. But if there is no existing customer record, you want to use the captured information to create one, and then associate the case record with the new customer.

If you want to create a dialog for that business process, which entity should it be written for? Not so obvious, right? Phone Call might be a good candidate, but depending on your business requirements, it might be a little artificial to force a user to create a phone call activity simply to start the dialog!

Scenarios like this one come up a lot, and when they do, the right answer to the “which entity?” question might be that there really isn’t one. You might describe processes like this as “self-contained”. That is, the process itself gathers all of the information required to take the appropriate action, and there’s no need to start it from the context of a selected record.

Every process (workflow or dialog) requires an entity, however, so you have to select something! In situations like these the User entity is often the best choice.

Let’s illustrate these issues with an example. Suppose a process gathers information to create an opportunity record, but you also want the process to check whether a customer record already exists, and if not, create a new customer record before creating the opportunity. Heuristically, the flow looks like this:

1. Gather basic contact information
2. Search for existing contact record
   1. If contact found
      1. Create new opportunity record, associate with existing contact record
   2. If contact not found
      1. Create new contact record
      2. Create new opportunity record, associate with new contact record

This is a good example of requirements for a self-contained process: unless the process is kicked off with a phone call (or some other record type) 100% of the time, it’s a forced fit to select one. What the user really wants in this situation is to “click a button and make it happen”! And while creating a dialog process against the User entity does not automatically provide this capability, it gets us pretty close.

We’ll examine a dialog process – Opportunity Intake – that has the following properties:

For any reasonably complex process – and this one is in that category – you should follow some best practices; at a minimum, I’d recommend:

• Structure it in logical stages in the Step Editor.
• Adopt a naming convention for process components like Response and Query labels, actions like Create Records and some others. This is an important topic and we will discuss it in detail elsewhere, but in this example you can see it in action.

The next figure shows Stage 1. We start with page that gathers first and last names, and a Yes/No radio button prompt for whether to create a new opportunity record. As you will see below, this last prompt isn’t strictly necessary, but I included it in case we need to extend functionality later.

Next comes Stage 2, where things start to get interesting. It starts out with a query, which uses the first and last name values entered in Stage 1, and constructs a dynamic query to search for that contact. Next, the query results are tested to see whether any potential matches were located. If so, they are presented in a prompt and response, and the selected one is stored in the “Response: Selected Contact” variable. If not, then a second set of prompt and response pairs are presented on a different version of Page 2, and the response are then used to create a new contact record.

Perhaps the most interesting part of Stage 2 is the query that searches for existing contact records based on the first and last names gathered on Page 1. The query (shown in the next two figures, which you’d access by clicking Set Properties on the Query line) uses the trick discussed earlier in the book: on the Design New tab, enter placeholder values (e.g., “fistname” and “lastname”) in the query designer for the First Name and Last Name fields:

Then, click the Modify Query Variables tab and use Dynamic Values to substitute in the Response Text from the Response: First Name and Response: Last Name variables. (If you work through an example like this you will start to appreciate the importance of a naming convention like the one I use here!)

One more thing about the query: notice the Operator is set to Like, rather than Equals. Refer back to the previous figure and notice the use of Contains rather than Equals. In a query like this you will almost certainly want the more forgiving Like operator, which corresponds to Contains in the Advanced Find UI.

Finally we get to Stage 3. If we don’t stop the dialog in the event the user responded No to the Create Opportunity? Prompt back in Stage 1, the Otherwise clause creates the new opportunity record. The only question is whether to attach it to an existing contact or to the new one created by the dialog, and we can apply the same checks here as before. This is shown in the next figure.

So, suppose you save and activate that dialog. Remember, it was created for the User entity, so you might think the only way to run it is to perform the following steps:

1. In the site map, click Settings, and then click Administration.
2. Click Users, select the user to associate the dialog with, and in the Process section of the ribbon, click Start Dialog.

   

3. Select the dialog and click OK to kick it off.

But if that’s all we can do, why is User any better than any other record type? Excellent question. Please proceed to the next section!

URL-Addressable Forms

Run a dialog – any dialog – and on the first page, press the Ctrl+N key combination to open a new Internet Explorer window. The following figure illustrates this in the context of the Opportunity Intake dialog:

Notice that the URL is exposed in the new window’s address box. If you select the URL, copy it with Ctrl+C and paste it with Ctrl+V, here’s what it will look like:

https://acme062811.crm.dynamics.com/cs/dialog/rundialog.aspx?DialogId=%7b95E011A1-FE9F-E011-86D6-1CC1DE798391%7d&EntityName=systemuser&ObjectId=%7bE113A45E-218C-4027-921D-B8F0100564C0%7d

The format of this URL is important, as it’s defined by a feature of Dynamics CRM referred to as “URL-addressable forms”. This means that (almost) any form or window in Dynamics CRM can be accessed not only through the user-interface, but also directly, by its URL. To understand how you can exploit URL-addressable forms to customize the user experience, let’s break down this initially nasty looking example:

Note: If you’ve ever wondered what those %7b and %7d things are in URLs like this, there’s an excellent explanation at www.w3schools.com , specifically: http://www.w3schools.com/TAGS/ref_urlencode.asp

Basically, these are the URL-encoding characters for ASCII characters included in a URL. Since URLs often contain characters outside the ASCII set, these URL-encoding characters perform the conversion for us. Dynamics CRM commonly uses the “{” and “}” characters to enclose a GUID, so instead of {E113A45E-218C-4027-921D-B8F0100564C0}, a GUID inside a URL must be formatted like this: %7bE113A45E-218C-4027-921D-B8F0100564C0%7d

So…where are we, then? A good, easy way to appreciate the utility of URL-addressable forms is to drag and drop the URL to your desktop, to create a shortcut:

Finally, you can keep the shortcut in a folder with your other favorites:

Now if you’re thinking the approach I just described is a little bit hard-wired, you are correct: the URL just described will always run the dialog for the user referenced in the URL. That’s fine for the do-it-yourself shortcut trick, but what you will probably want to do is create a way for any user to “click a button” and run a dialog process as themselves – that is, for the current user. That takes a little bit of Jscript, and we will cover that next.