Telemetry Dashboard is an Excel 2013 workbook that displays compatibility and inventory data about the Office files, Office add-ins, and Office solutions that are used in an organization. It is used as part of the modern Office compatibility process that is described in Assess Office 2013 compatibility. For a visual representation of the Telemetry Dashboard components and how they work, see Telemetry in Office 2013. This poster includes a description of all components, a list of what Office files are monitored, how data collection works, and more.

This article helps you deploy the 5 components of Telemetry Dashboard: the dashboard itself, the Telemetry Processor, the Telemetry Agent, the telemetry database, and a shared folder. Make sure that you review Plan for Telemetry Dashboard topology and hardware for topology, scalability, and hardware guidance before you deploy these components.

Telemetry Dashboard is an Excel workbook that is configured to connect to a telemetry database. Telemetry Dashboard is installed together with Office Professional Plus 2013, Office Standard 2013, and Office 365 ProPlus editions of Office 2013. To view it, you must have Excel 2013 installed. You can download Office 2013 from the Evaluation Center.

After Office 2013 is installed, you can start Telemetry Dashboard by using one of the procedures in the following table:

How to start Telemetry Dashboard

Operating system

How to start Telemetry Dashboard

Windows 7, Windows Server 2008, or Windows Server 2008 R2

From the Start menu, choose All Programs, then Microsoft Office 2013, then Office 2013 Tools, then Telemetry Dashboard for Office 2013.

Windows 8 or Windows 8.1

On the Start screen, type Telemetry Dashboard and then choose it from the search results.

Windows Server 2012 or Windows Server 2012 R2

Swipe in from the right edge to show the charms and then choose Search to see all the apps that are installed on the computer. Next, choose Telemetry Dashboard for Office 2013.

Note:

You can complete tasks in all Office 2013 suites by using a mouse, keyboard shortcuts, or touch. For information about how to use keyboard shortcuts and touch with Office products and services, see Keyboard shortcuts and Office Touch Guide.

SQL Server must be deployed before you can configure Telemetry Dashboard. You don’t have to have an existing database, but you do have to install or have access to one of these versions of SQL Server:

SQL Server 2005

SQL Server 2005 Express Edition

SQL Server 2008

SQL Server 2008 Express Edition

SQL Server 2008 R2

SQL Server 2008 R2 Express Edition

SQL Server 2012

SQL Server 2012 Express

The Getting started worksheet in Telemetry Dashboard provides a link to download SQL Server 2012 Express. If you don’t have SQL Server already installed, follow the steps in To download and install SQL Server 2012 Express. Be sure to review the following guidelines before you install SQL Server 2012 Express.

Make sure that the computer meets the hardware and software requirements for SQL Server 2012. This is especially important if you are planning an all-in-one configuration for testing because SQL Server has additional requirements, such as installing Windows service packs that aren’t required for Telemetry Dashboard. These requirements are described in Hardware and Software Requirements for Installing SQL Server 2012.

For local installations, you must run Setup as an administrator. If you install SQL Server from a remote shared folder, you must use a domain account that has read and execute permissions on the remote shared folder. For more information, see Install SQL Server 2012 from the Installation Wizard (Setup).

To download and install SQL Server 2012 Express

In Telemetry Dashboard, on the Getting started worksheet, under 1. Set up prerequisites, choose the link to download and install SQL Server 2012 Express with Tools. Choose the 32-bit or 64-bit edition, as appropriate. Or use this link: Microsoft SQL Server 2012 Express.

The setup process for SQL Server 2012 Express takes a while to download and extract files. Accept the various prompts and wait for the first page of SQL Server 2012 Express, which is named the SQL Server Installation Center, to appear after extraction is completed. Then, follow these steps:

In the SQL Server Installation Center, choose New SQL Server stand-alone installation or add features to an existing installation.

Telemetry Processor runs on one or more computers and collects inventory, usage, and telemetric data from the telemetry shared folder and imports the data to the telemetry database. Telemetry Processor is installed as a Windows service named “Telemetry Processor.”

We recommend the following operating systems for computers that run Telemetry Processor:

For production environments For best performance, we recommend these operating systems:

Windows Server 2008

Windows Server 2008 R2

Windows Server 2012

Windows Server 2012 R2

For test or small production environments You can use computers that run Windows 7, Windows 8, and Windows 8.1 in test environments and in small production environments. There is a limit of 20 concurrent connections for client operating systems, but in small environments, the agent randomization setting should minimize any chances of more than 20 agents connecting at one time.

Make sure that you have the following available before you run the Telemetry Processor wizard.

SQL Server instance name. The example used earlier is “teledash.”

SQL database. A new database will be created if you don’t specify an existing database.

Permissions to create a shared folder, or the UNC path of an existing shared folder. The Telemetry Processor wizard can create a shared folder if it has permissions to do so. If you specify an existing shared folder, any existing NTFS and shared folder permissions are overwritten with permissions set by the wizard.

Permissions to create a database (sysadmin role in SQL Server). To create and configure a new database, the account that runs the Telemetry Processor wizard must be a domain account that is a member of the sysadmin server-level role on the SQL Server. For ongoing use of Telemetry Dashboard, membership in the sysadmin role isn’t required and can be removed after the database is created. You can also use an existing database.

At least 11 GB of hard disk space. This disk space is needed to temporarily store telemetry data that is collected from users.

To install Telemetry Processor

In Telemetry Dashboard, on the Getting started worksheet, choose the installation link under 2. Install Telemetry Processor. Select the x86 or x64 version that’s the same as the Windows operating system architecture where Telemetry Processor will run.

Optionally, you can use the links in Telemetry Dashboard to save the .msi file to another computer and run the Setup program there. This step is required if you are installing Telemetry Processor on separate computers.

Choose Next and then choose Yes to accept the User Account Control prompt to install the Telemetry Processor. Choose Finish, which starts the Telemetry Processor settings wizard.

Choose Yes to accept the prompt, and then choose Next.

Type the name of the SQL Server instance, and then choose Connect.

Type the name of a new database, choose Create, and then choose Next.

Choose Yes to create database permissions and the database role.

Do one of the following on the Shared Folder page:

Specify the UNC path of an existing shared folder, and then choose Next. Choose Yes to allow the wizard to set the appropriate permissions.

To create a new shared folder on the local computer, choose Browse. Navigate to the location where you want to create the shared folder. open the shortcut menu for the parent folder (right-click it), point to New, and then choose Folder. Type the name of the new folder, make sure that you choose the folder again to select it, and then choose Select Folder. Choose Next, and then choose Yes to allow the wizard to share the folder and set the appropriate permissions.

Accept the default option to sign up for the Customer Experience Improvement Program, or choose the option not to sign up for the program at this point, and then choose Next.

Choose Finish to exit the wizard.

Note:

The Telemetry Processor generates error logs in a file that is named DPERRORLOG.txt. It is located in a hidden folder at %systemroot%\ServiceProfiles\NetworkService\AppData\Local\Temp.

The telemetry database, which was created by the Telemetry Processor settings wizard, is ready to be configured and connected to Telemetry Dashboard.

To connect to the telemetry database

In Telemetry Dashboard, on the Getting Started worksheet, under 5. Connect to the database to view telemetry data, choose Connect to Database.

Specify the name of the SQL Server and SQL database that you specified during the installation of Telemetry Processor.

When the connection is established, many new worksheets are added to the workbook. They won’t contain data until you deploy and enable Telemetry Agents.

To grant other administrators permission to access the telemetry database

You can use the Telemetry Dashboard Administration Tool (Tdadm) on the computer that is running SQL Server to allow other administrators to view data in Telemetry Dashboard. You don’t have to run this for your own account if you created a database when you installed Telemetry Processor. Update the values for dbserver, dbname, and domain\user as needed.

If your data (for example, file names, solution names, user names, computer names, or tag values) includes supplementary characters (surrogate pairs), use the following SC collations that are available in SQL Server to support better handling of the characters.

Version 90 Windows collations, such as Chinese_PRC_Stroke_90

Version 100 Windows collations, such as Latin1_General_100_CI_AS_SC

For more details about collation settings, see the documentation for the version of SQL Server that you are using.

Telemetry Agent collects inventory, usage, and telemetry data and uploads it to a shared folder. To help you filter and organize this data when it is displayed in Telemetry Dashboard, you can assign up to four custom labels for each agent to describe the client computer’s physical location, the user’s business group, user role, or other identifier.

The following information and instructions will help you learn more about Telemetry Agent and how to deploy and enable it.

You can assign as many as four labels to each user. This helps you analyze telemetry data for specific business groups, types of users, or any other designation that you choose. Use the following resources to help you plan the labels that you want to use before you deploy and enable the agents:

Telemetry Agent is built into Office Professional Plus 2013 and Office 365 ProPlus editions of Office 2013 and doesn’t have to be deployed separately. If your organization has any of the following versions of Office, you must deploy the agent to these clients.

Telemetry Agent must run one of the following versions of Windows (either 32-bit or 64-bit):

Windows 8.1

Windows 8

Windows 7

Windows Vista with Service Pack 2

Windows XP with Service Pack 3

Windows Server 2012 R2

Windows Server 2012

Windows Server 2008 R2

Windows Server 2008

Windows Server 2003

Important:

Telemetry Agent might not work correctly on Windows service packs that are no longer supported by Microsoft. We recommend that you verify that your service pack is supported on the Microsoft Product Lifecycle Search website before you install the agent.

In Telemetry Dashboard, on the Getting started worksheet, under 3. Deploy Telemetry Agent, choose the appropriate link (x86 or x64) to save the Telemetry Agent .msi file to a specified location.

Using your preferred method, deploy the .msi file to client computers that you want to monitor. Be sure to match the x86 or x64 version of Telemetry Agent to the architecture of the Windows operating system that is running on the client, not the Office client architecture.

For client local installations, you must run the .msi file as an administrator. You can deploy the MSI package silently by using the /quiet parameter with the MSI. Refer to the MSI help for the full set of available parameters.

To configure and enable Telemetry Agent, you can edit the registry on each monitored client computer in small or test environments. For production environments that contain hundreds or thousands of client computers, you can use Group Policy administrative templates. Note that two settings, AgentInitWait and AgentRandomDelay, are configurable only in the registry.

The easiest way to update the registry on a single client is to run a .reg file that sets the registry values that enable Telemetry Agent to collect and upload data. You can create this .reg file by copying one of the following examples to a text file, updating the required fields, saving the file as agent.reg, and running it from an elevated command prompt. In the .reg file, make sure that you specify the UNC path of the shared folder to which the agent uploads the data. Optionally, you can update the <TAG> fields so you can easily identify the collected data in your organization, such as by department, location, or deployment group.

The following example sets the default settings that are needed to enable Telemetry Agent. AgentInitWait and AgentRandomDelay are set to their default values, which are appropriate for production deployments.

The code in the following example enables Telemetry Dashboard to begin uploading data immediately by setting AgentInitWait and AgentRandomDelay to their smallest values. Use this example only in test deployments.

You can distribute registry updates to multiple client computers by putting a .reg file in a shared folder and instructing users to run the file, or you can add a command to the users’ logon script to automatically import the .reg file when users log on. Use the syntax in the following example to start the .reg file from a logon script:

If you’re not an administrator, you’ll have to edit the registry under HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\OSM. Just be aware that these changes can be overwritten by policy settings that are located in HKEY_CURRENT_USER\Software\Policies\Microsoft\Office\15.0\OSM.

Turns on the data uploading feature in the Telemetry Agent so that the agent can periodically upload telemetric data to the shared folder that is specified in CommonFileShare.

Value:

0 = Do not upload

1 = Upload

Default = 0 (Do not upload)

Required

commonfileshare

REG_SZ

Specifies the UNC path of the shared folder for storing telemetry data.

Value:

\\server\share

Required

tag1

tag2

tag3

tag4

REG_SZ

Adds custom tags to the Office telemetric data that is sent by Telemetry Agent. If you enable this policy setting, the specified custom tags are shown in Telemetry Dashboard, where you can filter the collected data by the tag name. You can replace tag1, tag2, tag3, and tag4 with custom strings to categorize and filter the collected data (for example, replace tag1 with a department name, replace tag2 with the location of the users, and so on).

Value:

tag1

tag2

tag3

tag4

Optional

enablefileobfuscation

REG_DWORD

Configures the Telemetry Agent to disguise, or obfuscate, certain file properties that are reported in telemetric data. If you enable this policy setting, the Telemetry Agent obfuscates the file name, file path, and title of Office documents before uploading telemetric data to the shared folder. You can learn more about file obfuscation and other privacy settings for Telemetry Dashboard in Manage privacy settings in Telemetry Dashboard.

Adjusts the time that the agent waits before it scans a client and uploads data to the telemetry shared folder. If this value doesn’t exist, the default wait time is 10 minutes (600 seconds). In test environments, you can specify 1 second to remove the delay for testing Windows 7 and earlier clients. We recommend that you set this to at least 60 seconds for computers that run Windows “8.”

Adjusts the maximum random delay, in minutes. The agent randomly waits between 0 and AgentRandomDelay minutes, in addition to the AgentInitWait value, before it starts to scan or upload telemetry data. If this value doesn’t exist, the agent waits between 0 minutes to 240 minutes. In test environments, you can specify 0 to remove the random delay for testing.

Prevents telemetric data for specific solutions from being reported to Telemetry Dashboard. However, the solution type is still reported. You can learn more about this registry setting in Manage privacy settings in Telemetry Dashboard.

You can also use Group Policy to enable and configure Telemetry Agents. Download the Group Policy admininstrative template files from the Microsoft Download Center. The policy settings that are listed in the following table are available in the path User Configuration\Administrative Templates\Microsoft Office 2013\Telemetry Dashboard.

Telemetry Agent policy settings

Setting name

Description

Required or optional

Turn on telemetry data collection

Turns on the data collection features in Office that are used by Telemetry Dashboard and Telemetry Log. By default, data collection is disabled in Office 2013.

Required

Turn on data uploading for the Telemetry Agent

Turns on the data uploading feature in the Telemetry Agent so that the agent can periodically upload telemetric data to a shared folder. By default, data uploading is disabled.

Required

Specify the UNC path to store Office telemetry data

Specifies the Uniform Naming Convention (UNC) path of a shared folder to which the Telemetry Agent sends Office telemetric data.

Required

Specify custom tags for Office telemetry data

Adds custom tags to the Office telemetric data that is sent by the Telemetry Agent. If you enable this policy setting, the specified custom tags are shown in the Telemetry Dashboard, where you can filter the collected data by the tag name. You can specify any string that you want to categorize and filter the collected data (for example, department name, title of user, and so on).

Optional

Turn on privacy settings in Telemetry Agent

Configures the Telemetry Agent to disguise, or obfuscate, certain file properties that are reported in telemetric data. If you enable this policy setting, the Telemetry Agent obfuscates the file name, file path, and title of Office documents before uploading telemetric data to the shared folder.

When a user logs in to an Office client, the Telemetry Agent waits 10 minutes to allow other logon processes to be completed, and then waits a randomized number of minutes up to 4 hours (or the max delay that is set for the AgentRandomDelay registry value) to avoid client computers sending data to network at the same time. After this initial scan, the Telemetry Agent scans and collects data every 8 hours.

If you want to trigger the data collection manually and see data uploaded immediately to Telemetry Dashboard, set the following registry values as described in the earlier table:

For computers that run Windows 7 and earlier

AgentInitWait: 1

AgentRandomRelay: 0

For computers that run Windows 8

Because user logon is faster in Windows 8, we recommend setting AgentInitWait to at least 60 seconds to make sure that the network connection is ready after the user logs on.

A: If a monitored client is disconnected, or if the telemetry shared folder is temporarily unavailable, data is still collected locally on the client. When the connection is restored, the backlog of information is delivered to the telemetry shared folder.

Q: How much data is transferred during each transfer?

A: The amount varies according to the number of files that are used and solutions installed. Here are estimates for how much data Telemetry Agent sends for different versions of Office:

Earlier versions of Office send approximately 50 KB for every upload.

Office 2013 sends approximately 64 KB of data for every upload.

The amount transferred can be larger when the interval is set to longer than the default or when the data sits idle on the local computer for long periods of time. Note that actual file content isn’t transferred; only metadata about the files is transferred.

Q: What is the performance impact of Telemetry Agent?

A: The agent is transparent to the user and performs low-impact tasks, such as inspecting content from MRU and specific local registry settings. The agent doesn’t actively scan files. The agent does account for monitor power state and network status to avoid affecting client performance.

Q: How can I re-initialize an agent?

A: Telemetry Agent is stored locally on the client computer at %localappdata%/Microsoft/Office/15.0/Telemetry/. (On computers that run Windows XP, the location is %userprofile%\Local Settings\Microsoft\Office\15.0\Telemetry). You can delete the contents of this folder to reinitialize the computer and start a fresh discovery. Note that this is a per-user data location.

Q: How frequently is data sent to the telemetry shared folder?

A: Data is transferred from the client to the telemetry shared folder when users log on and every 8 hours while the user is logged in. You can adjust this interval in Task Scheduler.

Q: What is the format of the collected data?

A: Collected data is stored and transferred in binary format to optimize the storage and data transfer requirements.

Q: If I change the custom labels after I deploy the telemetry agents, when will the new labels be updated in the telemetry database?

A: Only files that are in the Most Recently Used list will have their labels updated in the telemetry database. This will occur the next time the telemetry agent sends usage data. For files that are not in the Most Recently Used list, they will continue to show the old labels in the telemetry database until the user opens the file and the telemetry agent uploads usage data.

The following table describes some symptoms that you might encounter after you deploy Telemetry Dashboard and its components.

Troubleshooting Telemetry Dashboard deployments

Issue

Description

Resolution

Telemetry Processor Settings wizard fails

The wizard fails with the message “The Telemetry Processor settings wizard can only run on computers that are joined to a domain. Join the computer to a domain and run the wizard again.”

The computers that run the Telemetry Processor, shared folder, and SQL database must be joined to a domain so that the appropriate security settings can be configured. Make sure the computer or computers are in trusted domains.

Telemetry Agent isn’t scanning or uploading data. The Msoia.exe process runs in Task Manager for a long time.

By default, Telemetry Agent has an initial wait timer and randomization feature to avoid uploading large amounts of data at the same time as other agents and affecting network bandwidth. Update the AgentInitWait and AgentRandomDelay registry values to remove this delay in test environments. Otherwise the upload process can be delayed for up to 4 hours and 10 minutes. These registry values are described in Enabling and configuring Office Telemetry Agent, earlier in this article. You can learn how to trigger scanning and uploading in Triggering data collection manually.

Telemetry Dashboard shows no data

Telemetry Agent doesn’t upload data. The Msoia.exe process runs in Task Manager for a long time.

Verify the network connection between the Telemetry Agent and the telemetry shared folder.

Verify that the computer is joined to a domain. The shared folder is configured to allow access only to users who are authenticated within the domain.

Check the information in the Last Run Result column in Task Scheduler. If the operation succeeds, it shows return code 0. If the agent cannot upload data to the shared folder, the message "The network name cannot be found” appears in the Last Run Result column. This is the only error that the agent logs in the Last Run Result column. If other errors are listed, they were caused by other reasons or the scheduled task didn’t run.

Telemetry Dashboard shows no data

Telemetry Processor isn’t working. There are many folders and files in the telemetry shared folder.

Verify the network connection between the Telemetry Processor and the telemetry shared folder. Was the Telemetry Processor configured by the Telemetry Processor settings wizard? The permissions on the telemetry shared folder can vary, depending on the Telemetry Processor location and the telemetry database. Run the Telemetry Processor settings wizard again from the shortcut on the desktop.

Telemetry Dashboard shows no data

Telemetry Processor is working but there are many folders and files under in the Failed folder under the telemetry shared folder.

Telemetry Processor processes the files in the shared folder to the database one time per minute. If Telemetry Processor fails to process the files 3 times, it will move the failed files to the Failed folder. See the Telemetry Processor Log (%windows%\ServiceProfiles\NetworkService\AppData\Local\Temp\dperrorlog.txt) for more information.

Telemetry Dashboard shows no data

Telemetry Processor isn’t working because of SQL Server authentication settings.

Check the authentication type for SQL Server.Telemetry Dashboard doesn’t support SQL authentication. You must use Windows authentication.

Telemetry Dashboard shows no data

Telemetry Processor isn’t working because of firewall issues betweenTelemetry Processor and the telemetry database.

Telemetry Processor isn’t working because of firewall issues between Telemetry Processor, the telemetry database, and SQL Express.

If there is a firewall between Telemetry Dashboard and the telemetry database, check whether the SQL port is enabled in the firewall configuration. The default port for SQL Express isn’t a fixed value. Check the port number in the SQL Configuration Manager and add the port to the firewall configuration. See Configure a Windows Firewall for Database Engine Access for more information.

Telemetry Dashboard shows no data

Telemetry Processor isn’t working.

See the Telemetry Processor Log (%windows%\ServiceProfiles\NetworkService\AppData\Local\Temp\dperrorlog.txt) for more information.

Telemetry Dashboard can’t connect to the telemetry database

Telemetry Dashboard shows an error message that states it can’t connect to the database because of SQL Server permissions.

Check the permission role for Telemetry Dashboard. Add the user to the td_readonly role by using OSQL, SQLCMD, Enterprise Manager, or the Telemetry Dashboard Administration Tool (Tdadm). See Telemetry database earlier in this article for more information.

Telemetry Dashboard can’t connect to the telemetry database

Telemetry Dashboard shows an error message that states it can’t connect to the database.

If there are two or more instances of SQL Server, make sure that the Data connection settings dialog box in Telemetry Dashboard uses the correct SQL Server instance in the format Servername\SQLServerinstance.

Telemetry Dashboard can’t connect to the telemetry database

Telemetry Dashboard shows an error message that states it can’t connect to the database.

If the SQL Server is SQL Express, make sure that the SQL Server instance name is correct. The default instance name for SQL Express differs from SQL Server, for example: Servername\SQLExpress.

Telemetry Dashboard can’t connect to the telemetry database

Telemetry Dashboard shows an error message that states it can’t connect to the database.

If the SQL Server default collation is case-sensitive (for example, the Japanese version of SQL Server is case-sensitive by default), make sure that you entered a case-sensitive database name in the Data connection settings dialog box in Telemetry Dashboard.

Telemetry Dashboard can’t connect to the telemetry database

After you upgrade to Office 2013 SP1, Telemetry Dashboard shows the error message Database connection failure. The database needs to be updated.