Best practices for using the Microsoft Learn Organizational Reporting service

Article
03/30/2023

This article describes the best practices for using the Learn Organizational Reporting service.

Upon using this data sharing service, you're acknowledging and accepting the Microsoft Learn Data Access and Sharing Agreement to enable Microsoft to share Learn data with your organization for Learn users signing in with your organization’s tenant ID. Read and understand this agreement before using the Microsoft Learn Organizational Reporting Service and including the output in any production environment.

Plan what reporting solution you'll use to visualize the data offered in this service

The Microsoft Learn Organizational Reporting service gives raw completion data to organizations and doesn't have any dashboards by default. You can take the data and export it to CSV to quickly view the data, but it needs to be joined together to be impactful.

We've provided a Learn Organizational Reporting Power BI template for SQL DB storage that has many standard data visualizations within it, but you can also use any reporting solution of your choice. Plan ahead what you would like to use, so you can connect it to the data storage as a part of the setup process.

Understand the Learn content model

In order to use the Microsoft Learn Organizational Reporting service response effectively, it’s important to understand the types of content available in Microsoft Learn and their relationships to one another. Review the Learn content types article for more information.

Notably:

UID stands for “Unique ID” and is unique for each content object. If a UID changes, even if the title or other metadata stays the same, the content is considered a new object.
Modules are the core object within the Learn training catalog. They're all capable of standing alone, in the sense that they teach a scenario or concept end-to-end within them and don't require taking prerequisite modules. For some, this is it and they aren't a part of a learning path. For others, they're bundled together in one or more learning paths that take a user through building more advanced concepts. A module doesn't have to be a part of a learning path, or it can be a part of one or more.
Units aren't written as standalone content. They're intended to be taken in a specific order for the module. For this reason, we include the link to the module detail page and the first unit so that users can start there and proceed through the content.

Understand how localization works in Learn and how localized content is reflected in the org reporting output

Microsoft Learn supports over 65 locales on the site and much of the content has been translated into these locales. We aim to make the content available in all the languages that the product(s) being taught in the content is available in, but not all locale experiences have translated content available.

When a locale record doesn't have the associated translation available, the content on the site and the API response “falls back” to English as the default. In the case of the API output, you'll see English metadata in other locale responses when fall back happens. However, the URL to the content will still point to the locale, even though the main content may fall back and the reason is to allow the user to still navigate the site in that locale (which will show the header/footer translated, and any other link that has translation available).

When updates are published to the English content, our localization pipelines work to get the localized versions updated as soon as possible – usually within a few days of the original change. You can see a full list of supported locales via the site footer (select the link to the language you're viewing the site in).

Our training content completion records are locale-agnostic, meaning, we don't differentiate localized versions of content as separate objects in our user training completion records. No matter what language a user completes a training in, they'll receive credit for the overall object, and we don't store a reference to what language it was completed in. This means if you implement the Learn Organizational Reporting service data in your learning experience, you'll need to take this into account and, if you load the content objects in as separate objects, implement an equivalency between them so that no matter which language the user completes the training in, they'll get credit for it in the other languages and not have to retake it.

Understand how content versioning works in Learn and how it's reflected in the org reporting output

Notably, content is being updated all the time. We publish updates typically twice a day. They may either be minor, such as minor text changes, or major, such as major revisions, additions, or deletions. In general, the content portfolio is managed as a massive, highly governed open-source project with thousands of contributors, and as such, changes are happening all the time. If you use the Learn Organizational Reporting service data in your production system, you should be aware of this and have your system able to handle it.

When new content objects are added, they'll appear as a new object (identified by UID) in the response. When content is modified, you can tell based on its last_modified value. When content is deleted, it will be removed from the response. Although there's sometimes a slight delay on content being updated in the API response, when a user follows the URL to the content, they'll always see the most current information. In the case of deletions, the old URL will redirect to the new content or experience.

There are no references to content versions at this time beyond the last_modified date.

Understand the limitations of the Organizational Reporting service

See Limitations in the Learn Organizational Reporting service feature overview article.

Refresh the data regularly

If you're using the catalog information from the Learn Organizational Reporting service data to support your business processes, or displaying for customers as a part of your site experience, make sure that you refresh the content at least once a day.

Notably, content is being updated all the time. We publish updates typically twice a day. They may either be minor, such as minor text changes, or major, such as major revisions, additions, or deletions. In general, the content portfolio is managed as a massive, highly governed open-source project with thousands of contributors, and as such, changes are happening all the time. If you use the Organizational Reporting service data in your production system, you should be aware of this and have your system able to handle it.

Ensure your joined Microsoft Entra information is refreshed regularly

In order to know who each completion record is referring to, you'll need to join the Organizational Reporting dataset data to your Microsoft Entra information, so names appear alongside the completion records. If you don't refresh your Microsoft Entra joined data, then you may have completion records with stale personnel data, or that are missing PII data associated with them.

Reference the developer documentation

The Learn Organizational Reporting service developer documentation has a full list of the data provided as a part of the response, and recommendations on how each field is recommended to be used to support great learning experiences.

Next steps

For more information to support you with the Learn Organizational Reporting Service, review the following articles: