The Microsoft Dynamics CRM Online November 2009 Service Update will change how we provision unique names. If ISV code makes a certain incorrect assumption about how to talk to CRM Online organizations, it will break for some orgs. Also, customers setting up an email router will have a minor change to the way they acquire the configuration information they need.
What’s in a name?
As it turns out, for CRM, quite a bit: So much that any given organization of CRM Online actually has three names. What are they?
Without drilling too much into why we have the org unique name (it’s a combination of CRM history, design negotiations with partner teams, and other factors that aren’t particularly interesting), let’s talk about where it’s used.
Using unique name in development
If you’re not a CRM ISV developer, pretend for a moment that you are. You’re writing a client application which connects to a CRM organization and manipulates some data there. In the multi-tenant CRM world, a particular Windows Live ID may belong to multiple subscriptions, so you use a web service called Discovery to discover which orgs the Live ID belongs to and where to access them. You also acquire permission to access those orgs from the Discovery service. The whole flow is documented in the CRM SDK, but I’ll summarize here:
Unique name matters only in step 5. The response you get from the Discovery service consists of an array of OrganizationDetail objects. OrganizationDetail includes properties containing all three names I’ve discussed, plus a few other items (see screenshot). The Discovery service will then expect you pass a RetrieveCrmTicketRequest object whose OrganizationName property matches OrganizationDetail.OrganizationName of the org you want. The ticket you receive in return will properly route you to the CRM instance you requested.
Your head may be spinning at this point, but have no fear. I’m done talking about code and we’ll go back to abstract concepts in the next section.
One other place you might need your unique name is if you set up the email router. In the past, you could just grab your URL name (https://<thispart>.crm.dynamics.com) to plug into the email router configuration manager because of the “catch” I’ve promised to explain below. Once the November 2009 Service Update ships, that will not be reliable.
So what’s changed?
Because of provisioning changes in the November 2009 Service Update, or “R4” as we called it during development, we updated our strategy for generating unique names. Prior to this release, we would re-use the URL name as the unique name. That made a lot of sense – it was already a short, unique string and we had it at just the right time (org unique name is used early in the provisioning logic for CRM Online). However, this had a downside: for both internal and external developers of CRM Online, unique name and URL name could accidentally be treated as identical. Nothing would break, and you might not even suspect you were doing anything wrong. For external (ISV) developers in particular, the temptation would be strong: it would avoid one of the exchanges with the Discovery service. Instead, you could just ask the user up front for their org URL, then pass that as the unique name.
(So here’s the catch I referred to above: you CAN currently see your unique name, because you know about the quirk that it’ll exactly match your URL name. For ISVs, it was a shortcut, but for the e-mail router, this was the expected way to get that information.)
Fast-forward to the development of this release. With our refactored provisioning code, we don’t have a URL name at the moment where we need a unique name. Instead we generate one internally. Going forward, it’s almost certain that URL and unique names will not match. We will not change any existing unique names as they are also meant to be static. Since they’re just opaque strings, it doesn’t really matter that some unique names were generated under the old regime and others under the new. However, if your ISV code makes any assumptions about URL and unique name matching, it’ll break once R4 hits.
Let me repeat that in case you skim blog articles for bold words:
If your code assumes that a customer’s URL matches his org’s unique name, that code will break for orgs provisioned after the November 2009 Service Update arrives.
Early in development, we actually broke some of our internal partner teams’ code with this change as well. Our internal dependencies on the unique name are much deeper than ISV code dependencies, so it’s not surprising that there were several touch points. Since CRM Online ISVs can’t avoid talking to the Discovery service in order to get a CRM ticket, I’m optimistic that very little code will need to be rewritten to accommodate this change. If you “do the right thing” and enumerate orgs on the Discovery service, you have nothing to worry about.
But what about the email router?
If you’re configuring an email router, you still need the unique name. But I stated in the beginning that it’s not visible in the app, and I pointed out that you can’t just use the URL anymore. So how will you get your unique name?
One option, of course, is to write a little SDK app that asks the Discovery service to enumerate your orgs. Then you can pluck out the right field from the OrganizationDetail object. That feels like overkill, and it’s not very friendly to non-developers, either.
A better option is for CRM to surface this information right in the app. We didn’t have a great place to put it since we’ve never had to surface internal details like this before. The team decided that the “least weird” place to put this information is on the WSDL download page. To get there, navigate to Settings > Customization > Download Web Service Description Files. The page should really be renamed “Developer Information” or something like that, but we didn’t make that change in this release. If you’re using an organization which hasn’t yet been upgraded to R4, you won’t have this entry on that page.
We’ve updated the email router configuration docs to reflect this new way of getting the appropriate setting. All orgs, once they’re on R4 bits, will have their correct unique name reflected on the WSDL page, whether they existed before or after the R4 release.
Prior to R4
Contoso Enterprises, Inc.
Blue Yonder Airlines