Provisioning ‘unique names’ changes in Microsoft Dynamics CRM

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?

1. • Friendly name.  This is the name you see in the upper right corner of the web application, and it’s a name you (or your CRM administrator) gave when you signed up for CRM Online.  In my screenshot, the friendly name is “Product Team Demo Org 1”.  It’s basically for cosmetic purposes: to reassure you that you’ve logged into your instance of CRM Online.

1. •  URL name.  This is part of the address where you access the web application.  For the same organization that I showed above, the URL is quite different: it’s “crm1”.  The URL is functional in the sense that it’s how you find your organization over the Internet, but internally in CRM, it’s mostly unused.
2. Unique name.  This is a name that you’re probably only familiar with if you are a CRM ISV developer.  This is a name used internally by CRM Online and some of our partner systems within Microsoft to refer to a specific organization.  Developers should treat it as an opaque string which carries no inherent meaning.  As I write this blog entry, you can’t see your org’s unique name directly – but there’s a catch which I’ll get to in the section “So what’s changed? below”.

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:

1. • Connect to Discovery, get “Passport policy”
   • Connect to Windows Live ID, passing in the “Passport policy”, in exchange for a WLID ticket
   • Connect to Discovery again, passing in the WLID ticket, to get a list of orgs the WLID belongs to
   • Select which org you want to connect to (perhaps by asking the user)
   • Ask Discovery for a CRM ticket to a particular org and the URL at which to access that org
   • Finally, connect to that org’s CrmService or MetadataService, passing in the CRM ticket for authentication

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.

Recap

365blog

See more articles from this author