When you deploy Telemetry Agent to clients, you can specify up to four labels that best describe your users. Labels are one of the key features of Telemetry Dashboard because they let you filter the collected telemetry data by geographical location, individual business groups, specific types of users, and so on.

By using labels, you can get great insights into which documents are most frequently used in specific locations, business groups, etc. This information helps you to determine the business-critical documents that you need to test for specific business groups before upgrading. For example, financial-related documents are not bubbled up when you view the company-wide document inventory that is shown in the first screenshot below. By filtering the data by “North America” and “Finance,” you can find the business-critical documents for the Finance group, as shown in the second screenshot.

 Document inventory without labels:

Document inventory filtered by “North America” and “Finance” labels:

The labels are applied per user (not per computer) through Group Policy or the registry. There are several different ways to deploy labels depending on the granularity by which you want to filter telemetry data. In this article, we introduce the following best practices for deploying labels in your specific environment.

• Use Group Policy and set labels based on your Active Directory structure.
• Use a PowerShell script to generate Group Policy Objects filtered by security group.
• Use a VBScript to set labels based on user information stored in Active Directory.

Use Group Policy and set labels based on your Active Directory structure

If your Active Directory environment has domain/site/OU configurations that can be used for labels, the easiest way to deploy labels is using Group Policy. For example, you can configure Group Policy Objects (GPO) linked to Africa, APAC, Europe, North America and LATAM domains, etc., to set labels for users who belong to those geographical domains. Please download the Office 2013 Administrative Template files (ADMX/ADML) to create a GPO. You can learn more about how to configure labels by using Group Policy in Enabling and configuring Telemetry Agent.

Use a Power Shell script to generate Group Policy Objects filtered by security group

Another way to deploy labels by using Group Policy is security filtering. With this method, you can leverage existing or newly created security groups to apply GPO for labels. For example, you may have security groups per business group such as Engineering, Finance, Marketing, Sales, and Support. You can then create a GPO to deploy a “Finance” label and filter the GPO by the “Finance” security group. This enables you to deploy a “Finance” label for users who are members of the “Finance” security group. By using security filtering of GPOs, you can deploy more granular labels than just linking a GPO to a domain/site/OU, but you will need to create GPOs for each of your target security groups.

To make it easier, we provide a Windows PowerShell script to automate generation/filtering of GPOs based on information contained in a CSV file. With this script, you can easily create multiple GPOs with or without security filtering (up to 1,000 GPOs) at once, as follows:

1.     Create a CSV file that has the GPO name, linked domain/site/OU, label names, and security group names used for filtering.

2.     Run the provided PowerShell script.

a.  The script will read from the CSV file and automatically create Group Policy Objects.

b. The script will link Group Policy Objects to the specified target domain/site/OU.

Please see Create Group Policy Object for Tags (Labels) of Telemetry Dashboard for more details on the Windows PowerShell script.

Use VBAScript and set labels based on user information stored in Active Directory

Don’t worry if you don’t have appropriate Active Directory structures or security groups that you can use for labels. We provide a VBscript that can be run on end users’ computers to populate labels to the local registry based on logon user information in Active Directory.

For example, a user object in Active Directory has information such as “Office,” “Department,” ”Job Title,” “Domain,” etc. The script will use that information from Active Directory and populate the labels to the per-user registry. Deploying the VBScript to end users via logon script or Group Policy will enable you to provision custom labels for your users.

Please see Add Tags (Labels) for Office Telemetry Dashboard for more details on the VBScript.

Q&A

Here are answers to a few of the questions that we've been asked about these scripts:

Can you use all three methods to label?
Yes, but you need to avoid GPO conflicts where different labels are applied to the same target/security group, etc. If GPO and VBScript set different labels to the same users, GPO will always win.

Is there a limit to the number of labels you can collect data against?
There are no technical limitations for the number of labels, but we recommend setting 1-50 labels in total to each label (label1-label4) so that you can easily pick a label in the dashboard. If you set more than 1,000 labels, it can be difficult to choose the right label.

Does label precedence matter?
The labels will be shown in alphabetical order.

Can you save a combination of label filters as a “template” and name it something so you can run it again without remembering the combination?
If you used GPO, the same GPO can be applied to another target, but for VBScript, there is no way to save a combination of labels.

Let us know how these scripts worked for you!

Thank you for reading. We hope these scripts will help you to smoothly deploy labels for your Telemetry Dashboard and let you see the power that labels add to your Office upgrade and monitoring scenarios. We welcome your questions or comments on these scripts. Please add your comments to this post or to the script repository!