We became quite familiar with the Online Management API while developing our XrmToolBox Plugin. In this post I’ll share a few of my observations.

Authentication

We’ve received the question a few times now: why do you need to setup an App in Azure Active Directory in order to use the XrmToolBox Plugin? The short answer is, “because that is how Microsoft implemented the API”.

I haven’t seen an official explanation from Microsoft as to why they did it that way, but I can take a guess.

First of all, the traditional Dynamics 365 auimgthentication is about logging into a specific instance; this means you have to provide the URL for the instance you are logging into. This doesn’t work for the Online Management API, since it’s job is to manage instances. In terms of security, the permissions can’t be based in any single instance, they need to be at the tenant level.

Secondly, using OAuth 2.0 is a much more modern form of authentication, and they’d probably change the way the traditional APIs work if it didn’t mean breaking everything.

I agree it’s a bit of a pain compared to other Dynamics 365 functionality where you just provide your username and password and off you go, but it makes sense to me why they did it.

Reliability, Documentation and Support

Overall we were quite satisfied with the reliability of the service. During our testing of the XrmToolBox plugin, the API performed consistently well. Obviously things like restoring large backups can take a while, but that’s not the API’s fault.

The documentation seems to be complete and pretty clear. It contains an overview, code samples, as well as details for all of the supported operations.

In terms of support for the API, we did have to reach out to Microsoft for assistance in one case. We were getting an error message when trying to create a backup saved to Azure Blob Storage. The issue occurred in our own Engineered Code tenant, which is located in the Canadian data centers. We tested in other tenants and it worked fine, so we didn’t think the issue was related to our plugin. When we reached out to Microsoft, unsurprisingly the first level of support had no idea what the API was. We were bounced around a little bit between Office 365, CRM and Azure support, and it took over a month, but eventually the problem was resolved. We never found out what the actual issue was, but I’m wondering if there was an issue specific to the Canadian (crm3) data centers.

Backup to Azure Storage Blob

To save someone else the hassle of figuring out if there are any limitations on which Azure accounts you can backup an instance to, we didn’t find any. As discussed above, we ran into some errors while backing up to Blob Storage. Our first thought was that it was a permissions issue, so we tried a number of different combinations (same/different user accounts, same/different data centers). In our testing we found that as long as the Azure Storage account name, account key, and container name are correct, it should work.

What We’d Like to See in the Next Version

While Version 1 of the API is great, there are a few things that we’d love to see included in the next version:

• Ability to Retrieve the Status of BackgroundOperationsEnabled for an Instance: When getting the details for a particular instance, one field we feel is missing is whether background operations are enabled. Currently there is a field for Admin Mode, but if that is true, there is no way to tell if background processes are enabled or not. This leads to a non-ideal UI in our XrmToolBox plugin, where we have to present a completely blank form for setting the Admin Mode, because we don’t have all the details for the current status. Having access to the current Notifications Text would also be helpful.
• Response Code If No Instances Are Configured: This may be more personal preference than anything, but I feel it’s a bit strange that we receive a 404 Not Found response when calling /api/v1/Instances if there are no configured instances. I would’ve thought that we’d simply get an empty list.
• Delete Backup: While possible via the Dynamics 365 Admin Portal, the API currently doesn’t allow us to delete an instance backup.
• Copy Instance: While possible via the Dynamics 365 Admin Portal, the API currently doesn’t allow us to copy instances (for example, from production to a sandbox instance).
• Edit Instance: While possible via the Dynamics 365 Admin Portal, the API currently doesn’t allow us to edit instances (for example, editing the instance type, name or URL).

I love the fact that Microsoft is giving us these types of APIs that make it possible to automate and integrate. Here’s hoping that it’s something they continue to enhance.