Business Central Telemetry Part 1: Consuming the API

With Business Central you get something called Business Central Admin Center, the place where tenant admins and delegated admins (the partner associated with the tenant) perform admin tasks like manage environments, set upgrade windows and view telemetry.

Everything you can do through the admin center can also be done through the APIs, today we’ll have a look at how to consume the telemetry API from a simple C# console application and create the foundation for the next blog post where we will go one step further and transform the data returned by the API into a proper JSON structure that can be sent to Azure Log Analytics.

Why should we care about telemetry?

Telemetry is incredibly valuable, even though the data we currently get back from the API is quite limited, we can still use it for troubleshooting, but more importantly, we can analyze how the application is being used and answer questions like:
– Is certain functionality still being used?
– How often is certain functionality used?
– Which pages are used the most?
– Which area of the application produces the most errors?

Once we have answers to those questions we can better prioritize our development and spend time on the things that really impact our end-users.

Create a Business Central sandbox tenant

The first thing we need to do is set up a demo tenant, any tenant should work as long as you have access to that tenant’s Azure Active Directory.
I’ve created my tenant by using Microsoft Demos, as described by Dmitry in this blog post.

Create the App Registration

Once you have the BC tenant in place, we need to create an App Registration for our console application in the tenant’s Azure Portal (free of charge) as described here.
It’s really important to choose Native for the Application Type and not Web App/API when you create the App Registration!

The App Registration’s Application Id and the AAD tenant id are needed for the console application to authenticate against the tenant’s AAD.

Produce some telemetry

In order to retrieve telemetry, we need to produce some telemetry first.
In Busines Central, I’ve created a new customer, two sales quotes and I’ve converted one of those quotes into a sales order.
Just those actions already produced around 5000 telemetry records, as you can see below, every function call is logged with a start and stop, so the real challenge will be to manage that big set of data and store it somewhere for further analysis.

Console Application overview

Let’s first have a look at the finished (for now) application and then go over the different methods.

In order to store the configuration I’ve used a simple JSON file that’s loaded once the application starts up, the configuration file looks like this:

Authentication

The first step will be to authenticate against the AAD of the demo tenant (TenantId setting), we do this by using the username and password of the tenant admin user (unfortunately, you either need the tenant admin user or the delegated admin user you get as a partner) and then we authenticate for a resource (ResourceURL setting) with the ApplicationId.
The code looks like this:

Note: the config.Authority is a string combined of the AzureADInstance and the TenantId setting.
The result is a token that’s used to create the authorization header that we then add to the HttpClient:

Calling the API

Now that we’ve got the authentication in place, we can call the API and get back some data, yaay!

The URI looks like this:
v1.1/admin/applications/{applicationFamily}/environments/{environmentName}/telemetry?startDateUtc={start}&endDateUtc={end}&logCategory={cat}
Where applicationFamily is ‘BusinessCentral’ and environmentName is ‘Production’
It is required to specify the startDateUtc and endDateUtc, if you omit those, you won’t get any results!
For this example, I’ve hard-coded the startDateUtc and endDateUtc for simplification.

The result of the API call looks like this, it’s a highly inconvenient structure containing queryColumns and queryResults.
The queryColumns contain the definition of the returned columns and the queryResults contain an array, where each array is an array of data.
Ideally, every queryResult consists of key-value pairs so you can easily deserialize the response to a class, but unfortunately, this is not the case.
In the next blog post, we will look at how to transform this response into a proper class so that we can send it to Azure Log Analytics.

Formatting the output

In order to transform the response to a more readable structure, we can deserialize the response to a dynamic object and then serialize it to JSON with indented formatting:

And that’s what we write to the console window:

In the next blog post we will have a look at how to transform the response into a proper class that we can then send to Azure Log Analytics.

2 Comments

Business Central Telemetry Part 1: Consuming the API - Robberse - Dynamics 365 Business Central/NAV User Group - Dynamics User Group · January 6, 2019 at 10:09 pm

[…] Richard Robberse 2019-1-6 10:23 PM 0 comments 0 views Mirror post […]

Business Central Telemetry Part 2: Sending Telemetry to Azure Log Analytics – Robberse IT Services · January 15, 2019 at 8:00 pm

[…] Previous PostBusiness Central Telemetry Part 1: Consuming the API […]

Leave a Reply to Business Central Telemetry Part 2: Sending Telemetry to Azure Log Analytics – Robberse IT Services Cancel reply

Your email address will not be published. Required fields are marked *