Use the Readiness Toolkit to assess application compatibility for Office 365 ProPlus

The Readiness Toolkit for Office add-ins and VBA can help you identify compatibility issues with your Microsoft Visual Basic for Applications (VBA) macros and add-ins that you use with Office. The Readiness Toolkit includes the Readiness Report Creator, which creates an Excel report with VBA macro compatibility and add-in readiness information to help your organization assess its readiness to move to Office 365 ProPlus.

You can download the Readiness Toolkit for free from the Microsoft Download Center.

Important

The Readiness Toolkit doesn't repair or fix the code in your VBA macros. If you create an advanced report, the report does provide guidance, when available, for remediating your VBA macro code.

The Readiness Report Creator can scan for VBA macros in Word, Excel, PowerPoint, Outlook, Access, Project, Visio, and Publisher files, for Office versions as far back as Office 2003. It can also scan for certain types of add-ins used with Office. Add-ins for all Office applications are identified, but it doesn't include web add-ins. For more information, see File extensions scanned for VBA macros and Types of add-ins for which the Readiness Report Creator collects data.

The download is an MSI file that you can use to install the Readiness Toolkit on a user's computer. After it's installed, when you run the Readiness Report Creator, a UI wizard steps you through the process of creating a readiness report. There is also a standalone executable that can be run from the command line or used with scripts. This is useful if you need to collect readiness information from users throughout your enterprise in a more automated manner. For more information, see Getting readiness information for multiple users in an enterprise.

The following information is provided to help you use the Readiness Report Creator:

Note

If you have feedback or questions about the Readiness Toolkit, please email us at ReadyForOffice@microsoft.com.

Creating a readiness report

Requirements and limitations for using the Readiness Toolkit

Before installing and using the Readiness Toolkit, you should be aware of the following requirements:

Note

We recommend using the 64-bit version of Excel, especially if you expect more than 400,000 results to appear in the readiness report.

Also, there a few limitations about the Readiness Report Creator that you should know about:

  • The Readiness Report Creator can't scan password protected files. If you try to scan one of these files, the file shows up as "Password protected" in the report.

  • The Readiness Report Creator can't scan files that are saved in a SharePoint document library, in OneDrive, or in some other type of cloud-based storage location. If you try to scan one of these files, the file shows up as "Cloud-based" in the report.

  • The Readiness Report Creator lists each issue with an Office document in a separate row in an Excel worksheet. Therefore, the Readiness Report Creator can only return 1,046,575 results. If you expect to exceed these limits, we recommend that you narrow the scope of your report, such as to a specific department.

Choosing the information to use to create your report

To create a readiness report, you first need to select what information to use to create the report. The following table lists the possible options and an explanation of each option. It also specifies which type of readiness report is created with each option.

Option Explanation Report created
Most recently used Office documents and installed add-ins on this computer
The Readiness Report Creator only scans Office documents that are in the user's list of most recently used files. This allows you to narrow the focus of the scan to documents that a user accesses on a regular basis.

In addition, the Readiness Report Creator looks for any add-ins for Office that are installed on the computer on which the Readiness Report Creator is run.
VBA and Add-in
Office documents in a local folder or network share.
The Readiness Report Creator scans the Office documents in the folder or network share that you specify. The Readiness Report Creator automatically scans the specified location, and all the subfolders in that location.

Note: With this option, the Readiness Report Creator doesn't look for add-ins installed on the computer on which the Readiness Report Creator is run.
VBA only
Previous readiness results saved together in a local folder or network share.
This option allows you to create a consolidated report comprised of individual readiness results from multiple standalone computers.

For example, you might want to run the Readiness Report Creator on all the computers in the Finance department, saving the results of each scan to a network share. Then, you can use this option to create a consolidated report for the Finance department.

For more information, see Getting readiness information for multiple users in an enterprise.
VBA only, or VBA and Add-in, depending on what readiness results are being used.
Add-in data from Office Telemetry dashboard.
If you're already using Office Telemetry Dashboard to assess add-in compatibility, you can use that information which you've already collected to create a readiness report. You just need to provide the Readiness Report Creator with the appropriate information to access the database for Telemetry Dashboard.

Note: With this option, the Readiness Report Creator doesn't look for VBA macros.
Add-in only

Choosing between a basic and an advanced report

After you select what information to use to create your report and specify a location to save your report, you need to choose whether to create a basic report or an advanced report.

We strongly recommend that you create an advanced report because an advanced report provides additional information to help you assess the compatibility of your VBA macros and add-ins with Office 365 ProPlus. For example, in an advanced report, you get the following additional information:

  • Remediation advice, when available, for issues found in your VBA macros. This information is shown in a separate worksheet in the report.

  • Readiness status for add-ins. For example, the report might show that the software provider has a supported version of the add-in for Office 365 ProPlus.

The readiness status for add-ins is derived from telemetry-based computations as well as explicit support statements from ISVs.

To provide you with the most up-to-date remediation advice and readiness status, the Readiness Report Creator contacts Microsoft when it creates the report. Some information about your VBA macros and add-ins is sent to Microsoft. For more information about what is sent, see Examples of the information sent to Microsoft when creating an advanced report.

Important: If you're creating an advanced report, make sure the computer on which you're running the Readiness Toolkit has access to the Internet. The Readiness Toolkit calls a publicly available web-service, so the following two URLs need to be whitelisted in your firewall:

Interpreting the information in the readiness report

The Readiness Report Creator creates a readiness report as an Excel file. The readiness information available in the report depends on what information you based your report on, as well as whether you chose to create a basic or advanced report.

Each report starts with an Overview page, which provides high-level information about the results, and links to the reports available - VBA or Add-in or both.

VBA readiness reports

The following table provides a list of the different tabs (worksheets) that are shown in a VBA readiness report.

Worksheet name Contents
VBA Overview
Displays three pie charts to provide a high-level overview of the results of the scan.

Each pie charts shows different information: the status of the files scanned, the readiness status for the unique macros found during the scan, and readiness status of the unique files scanned. See the tables later in this section for more information about the file status and readiness status values that appear in these pie charts.

The Readiness Toolkit creates a unique hash of the VBA macro code to identify macros that are reused in multiple files. The Readiness Toolkit does something similar to identify duplicate files. The Readiness Toolkit does this to provide you with a more realistic assessment of how many unique VBA macros and unique files need to be evaluated.

Note: If you plan to deploy the 64-bit version of Office 365 ProPlus, be sure that the "Include 64-bit readiness data" check box is selected and that you've refreshed the report.
VBA Summary
Provides some pre-defined PivotTables to allow you to analyze the data captured from the scan.

If these PivotTables don't meet your specific needs, you can create your own based on the data on the VBA Results worksheet.
VBA Results
Provides information on each file scanned by the Readiness Report Creator. If multiple issues are found in a scanned file, there is a separate row for each issue.

See the table under the "Detailed VBA information" heading at the end of this section for an explanation of the information that appears in each column.
VBA Remediation
Provides proposed changes to VBA macro code found during the scan.

See the table under the "Detailed VBA information" heading at the end of this section for an explanation of the information that appears in each column.
VBA References
List references identified in code and in the VBA project. These references are generally used to call external DLLs or linked files for use by the VBA code.

See the table under the "Detailed VBA information" heading at the end of this section for an explanation of the information that appears in each column.

File status: The report also categorizes, by a file status, the files that were scanned. The following table lists the possible file statuses that can appear in a readiness report, and an explanation of the file status.

File status Explanation
No VBA
The file was scanned and no VBA macro code was found.
Has VBA
The file was scanned and VBA macro code was found.
Cloud-based
The file couldn't be scanned because it is saved in a SharePoint document library, in OneDrive, or in some other type of cloud-based storage location.
Password protected
The file is password protected so it couldn't be scanned for VBA macros.
Inaccessible
The file couldn't be scanned for some reason, such as the Readiness Report Creator had insufficient permission to access the file, the file is corrupted, or the file uses a very old Office file format.
Locked
The file was locked or in use when the scan was performed.
Error
The VBA code stream trying to be read during the scan wasn't in a valid format. Sometimes opening, and then saving, the file in a supported Office version will allow the Readiness Report Creator to scan the file.

Severity level: The report categorizes, by a severity level, the issues found with the VBA macros to help you estimate how much effort it will take to address the issues found. If multiple issues are found with a VBA macro, the report displays the highest severity level in the pie chart.

The following table lists the possible severities that can appear in a readiness report, and an explanation of the severity level.

Severity Explanation
Ready to upgrade
No issues were found in this file and it's compatible with Office 365 ProPlus.
Code design awareness
While the code will function as expected and the user isn't likely to notice any change, the feature, property, or method works differently than previously or might be deprecated in favor of a newer version.
Minimal validation recommended
No runtime or compile time errors are expected, but the API functionality may have changed in some way. It's recommended that the user runs a spot check on the file with Office 365 ProPlus to ensure it continues to function as expected. To minimize environmental issues, ideally run the spot check on the computer that the macro usually runs.
Limited remediation required
Some refactoring of code will be required. But, there is a clear replacement and so the expectation is that the work required to fix the macro is significantly reduced.
Significant remediation required
Significant code refactoring will be required to enable the code to continue to function as it did in the legacy Office version. For example, an API that has been deprecated, but no replacement function has been provided. In this case, the only option available is to recreate the functionality.

Detailed VBA information: The VBA Results, VBA Remediation, and VBA References tabs in the VBA readiness report each contain similar columns of information. The following table provides a list of those columns, along with an explanation of what information is contained those columns.

Column name Explanation Example
Guideline
The guideline (rule) identified when document has been scanned.
Program Toolbars and Menu Bars will no longer be visible in Access 2013.
Severity
Severity of issue identified.
Significant remediation required
Source Location
Location of the file that was scanned.
D:\My Documents\My Files\
Source File
Name of the file that was scanned.
MyFileName.xlsx
Source File Hash
Uniquely generated hash for the file.
36426A0DCFC06F6425E205F107A5CA58
Source File Extension
Extension of the file that was scanned.
.docm
Module
Name of the module where the code issue was identified.
mDJSCommandBars
Line #
Line number where the code issue was identified.
112
Type
Type of issue that has been identified.
VBA
Member
VBA Module section name where the issue was identified (i.e. function).
CommandBars
Statement
The section of the code where the issue was identified.
Dim ctlName As CommandBarControl
VBA Hash
Uniquely generated hash for the VBA code.
CC-D2-F3-9C-58-48-04-E4-16-5B-B6-44-B3-EB-EB-FE
Reference
Link to description of issue and help content (where applicable).
https://technet.microsoft.com/library/cc178954.aspx
FileStatus
Classification of the status of the file that was processed.
Password protected
64Bit
Specifies if the issues identified is 64-bit specific.
Yes
UserHash
User of the file.
Katharine Cruz
DeviceName
Name of the device where the scan was performed.
Laptop01
Original code
VBA code found in the macro which may cause issues when moving to a 64-bit version of Office.
Private Declare Function FindWindow Lib "user32" Alias "FindWindowA" (ByVal lpClassName As String, ByVal lpWindowName As String) As Long
Proposed changes
Suggestions on how the VBA code in the macro can be updated to work correctly with a 64-bit version of Office.1, 2
Private Declare PtrSafe Function FindWindow Lib "user32" Alias "FindWindowA" (ByVal lpClassName As String, ByVal lpWindowName As String) As LongPtr

1 For more information about writing VBA code for 64-bit versions of Office, see 64-Bit Visual Basic for Applications Overview.

2 Important: All proposed changes are provided as is, with no warranty or guarantee. It's important to validate that all changes work as expected when you update your VBA macro code.

Add-in report

The following table provides a list of the different tabs (worksheets) that are shown in an add-in report.

Worksheet name Contents
Add-in Summary
Provides a high-level overview of the add-ins found by the Readiness Report Creator.

The data at the top of the worksheet is intended to give you a quick assessment of how many add-ins will likely be compatible with Office 365 ProPlus and how many add-ins you'll need to do more research on.
Add-in Details
Provides metadata information about the add-ins found (for example, publisher and version number), the total number of installs of each add-in, and, if an advanced report, the readiness status (for example, "Supported version available").
By computer name
Provides similar information to what's on the Add-in Details worksheet, but lists every computer that the add-in is installed on, instead of just a total number of installs for the add-in.

You can adjust what information is shown in the add-in report by selecting choices from the drop-down lists on the Add-in Summary tab, and then refreshing the report. For example, you can adjust the report to only show information about Access and Excel add-ins.

By default, add-ins that are shipped by Office aren't shown. If you want to see information about those add-ins, select "Yes" from the drop-down list and refresh the report. But, most enterprises won't need to worry about application compatibility of add-ins which are shipped with Office.

If you plan to deploy the 64-bit version of Office 365 ProPlus, be sure to select "64-bit" from the drop-down list and refresh the report. This provides 64-bit specific readiness information about the add-ins. The default selection for reports is 32-bit.

The following table lists the possible readiness statuses that you can see in the add-in report and an explanation of what each status means.

Readiness status Explanation
Highly adopted
This add-in is being widely used on Office 365 ProPlus in other organizations, and is ready for use with Office 365 ProPlus. But, the software provider doesn't officially support the add-in on Office 365 ProPlus.
Adopted
This add-in is being used on Office 365 ProPlus in other organizations, but the software provider doesn't officially support the add-in on Office 365 ProPlus.
Contact software provider
This add-in might have issues with Office 365 ProPlus. You need to decide if this add-in is business critical and then contact the software provider for guidance.
Supported version available
A supported version of this add-in for Office 365 ProPlus is available from the software provider.
Unknown1,2
This add-in is unknown to Microsoft. For example, it could be a line-of-business add-in that your in-house application development team created.

If you create a basic report, the readiness status for all add-ins is listed as Unknown. It's only when you create an advanced report that the Readiness Report Creator contacts Microsoft to try to get readiness status of add-ins.
Insufficient data2
Microsoft has seen this add-in but not enough information has been collected to provide a readiness status for this add-in.

1 Some of the add-ins that ship by default with Office are currently flagged as Unknown in an add-in readiness report. These add-ins are actually Highly Adopted and are supported by Microsoft. Here are the names of those add-ins: ActionsPane Schema for Add-Ins, Analysis ToolPak, Analysis ToolPak - VBA, Date (XML), Conversation History Add-in for Microsoft Office 2016, Euro Currency Tools, Instant Messaging Contacts (English), Measurement Converter (Measurement Converter), Microsoft Actions Pane 3, Skype Meeting Add-in for Microsoft Office 2016, Solver Add-in, Telephone Number (XML), and Time (XML).

2 For more information, see Possible steps to take for add-ins classified as "Unknown" or "Insufficient data".

Detailed add-in information: The "Add-in Details" and "By computer name" tabs in the add-in report each contain similar columns of information. The following table provides a list of those columns, along with an explanation of what information is contained in those columns.

Column name Explanation
Machine name
The name of the computer on which the add-in is installed.

This column only appears on the "By computer name" tab.
Add-in Name
The name of the add-in.
Add-in Publisher
The name of the add-in's publisher.
Add-in Version
The version of the add-in.
App
The Office application that the add-in is used in. For example, Word or Excel.
Total Installs
The total numbers of installs of the add-in.

This column only appears on the "Add-in Details" tab.
Readiness status (32-bit)
The readiness status for the add-in. Advanced reports only.

See the table above for a list of possible readiness statuses.

Note: If you chose "64-bit" from the drop-down list on the "Add-in Summary" tab, this column name displays as "(64-bit)" instead.
Remarks
Additional information, if available, about the readiness status of the add-in. Advanced reports only.
More information
Link to additional readiness information about the add-in. Advanced reports only.

Getting readiness information for multiple users in an enterprise

It's easy enough to install and run the Readiness Report Creator on a single user's computer to create a readiness report. But what if you're in a large organization and need to create readiness reports for an entire department or branch office?

Along with the UI wizard version of the Readiness Report Creator, there is also a standalone executable that can be run from the command line or used with scripts. It's named ReadinessReportCreator.exe and is located in the folder where the Readiness Toolkit is installed.

If you have your users run the UI wizard version of the Readiness Report Creator, you end up with separate Excel files, one for each user. That makes it difficult to see readiness from a departmental or office-wide perspective. You also have to rely on the users to run the Readiness Report Creator and follow the instructions correctly.

The better alternative might be to use the command line capabilities of the Readiness Report Creator and use a script to run the Readiness Report Creator to collect the information on behalf of the user. You can save the files created by the Readiness Report Creator to a network share. If you do this, make sure that the appropriate write permissions are given to the share.

You can see a list of the available command line options by opening a command prompt, navigating to the folder where you installed the Readiness Toolkit, and then typing the following command:

ReadinessReportCreator.exe -help

The command line version of the Readiness Report Creator doesn't have the all the same capabilities as the UI wizard version. You can use the command line version to scan the most recently used Office documents and installed add-ins on a computer, or Office documents in a local folder or network share.

The following is an example of a command line that you can run to scan for both VBA macros and add-ins, and save the results to a network share for the Finance department. Note that you have to include addinscan option as part of the command line for the add-in scan to occur.

ReadinessReportCreator.exe -mru -addinscan -output \\server01\finance -silent

The following is an example of a command line that you can run to scan a user's most recently used Office documents and save the results to a network share for the Finance department. This only scans for VBA macros.

ReadinessReportCreator.exe -mru -output \\server01\finance -silent

The following is an example of a command line that you can run to scan a folder, and all its subfolders, and save the results to a network share for the Finance department. This only scans for VBA macros.

ReadinessReportCreator.exe -p c:\officefiles\ -r -output \\server01\finance -silent

It's important to note that when you run the Readiness Report Creator from the command line, the Readiness Report Creator doesn't create an Excel file. Instead the Readiness Report Creator creates a TSV file or a JSON file. The TSV file contains the VBA macro information from the scan, and the JSON file contains the add-in information from the scan.

To create a consolidated Excel report from these various command line scans, you need to run the UI wizard version of the Readiness Report Creator. For the information source, select "Previous readiness results saved together in a local folder or network share," and then specify the location where you saved all the TSV and JSON files for the scans. The Readiness Report Creator then consolidates the information from the TSV and JSON files into a readiness report in a single Excel file.

Keep in mind that the Readiness Report Creator lists each issue with an Office document in a separate row in the Excel worksheet. Therefore, the Readiness Report Creator can only return 1,046,575 results. If you expect to exceed these limits, we recommend that you narrow the scope of your report, such as to a specific department.

Additional information

File extensions scanned for VBA macros

The following table lists, by application, the file extensions that are scanned when the Readiness Report Creator looks for VBA macros in Office documents.

Application File extension
Access
accdb, accdt, mdb
Excel
xla, xlam, xls, xlsm, xlsx, xlt, xltm, xltx
Outlook
otm
PowerPoint
pot, potm, potx, ppa, ppam, pps, ppsm, ppt, pptm, pptx, sldx, sldm
Project
mpp, mpt
Publisher
pub
Visio
vsd, vsdx, vsdm
Word
doc, docm, docx, dot, dotm, dotx

Types of add-ins for which the Readiness Report Creator collects data

The following table lists the types of add-ins that the Readiness Report Creator collects data on. Add-ins for all Office applications are identified, but it doesn't include web add-ins.

Add-in type Office applications Description
Automation
Excel
Excel-supported automation add-ins are built upon COM add-ins. Functions in Automation add-ins can be called from formulas in Excel worksheets.
COM
Excel, Outlook, PowerPoint, and Word
COM add-ins include add-ins usually written in C++ and Visual Studio Tools for Office (VSTO) developed using managed code.
VBA
Excel, PowerPoint, and Word
VBA add-ins are application-specific files that contain VBA code. These include macro-enabled Word templates (.dotm), Excel add-ins (.xla, .xlam), and PowerPoint add-ins (.ppa, .ppam).
WLL
Word
WLL (.wll) add-ins are specific to Word and built with any compiler that supports building DLLs.
XLL
Excel
XLL add-ins (.xll) are specific to Excel and are built with any compiler that supports building DLLs (dynamic-link libraries). They do not have to be installed or registered. XLL add-ins also include DLLs that contain user-defined commands and functions.
XLS RTD
Excel
XLS real-time data (RTD) add-ins are Excel worksheets that use the RealTimeData worksheet function to call an Automation server to retrieve data in real-time.

Examples of the information sent to Microsoft when creating an advanced report

When you choose to create an advanced report, some information is sent to Microsoft.

The following table provides a list of the information that is sent to Microsoft about the VBA macros that are found during a scan, along with examples.

Data Description Example
DevicesScanned
Number of devices that were scanned.
DevicesScanned: 23
UniqueUsers
Count of users included in scan.
UniqueUsers: 14
Rule
Count of how many times a specific rule was found to apply to the VBA macros scanned. A GUID is used to uniquely identify the rule.
48f05b1d-c8ad-4d0c-9453-1abdf007b2db: 23

74db65ab-76f3-43fb-997d-0d9750efb527: 2
FilesWithIssues
Count of unique files with compatibility issues.
FilesWithIssues: 320
FilesWithDuplicateVBA
Count of unique files containing duplicate macros.
FilesWithDuplicateVBA: 233
FilesWithNoIssuesFound
Count of unique files with no issues.
FilesWithNoIssuesFound: 12
InaccessibleFiles
Count of unique inaccessible files.
InaccessibleFiles: 4
FilesPasswordProtected
Count of unique files that were password protected.
FilesPasswordProtected: 123
FilesLocked
Count of unique locked files.
FIlesLocked: 0
FilesWithVBA
Count of unique files with VBA.
FilesWithVBA: 122
FilesWithoutVBA
Count of unique files without VBA.
FilesWithoutVBA: 11
Significantremediationrequired
Count of unique files that require significant remediation.
Significantremediationrequired: 12
Limitedremediationrequired
Count of unique files that require limited remediation
Limitedremediationrequired: 12
Minimalvalidationrequired
Count of unique files that require minimal validation.
Minimalvalidationrequired: 22
CodeDesignChanges
Count of unique files that contain use of features that we would recommend changes.
CodeDesignChanges: 1

The following table provides a list of the information that is sent to Microsoft about the add-ins that are found during a scan, along with examples.

Data Example
Add-in Prog ID
UCAddin.LyncAddin.1
Friendly Name
Skype Meeting Add-in for Microsoft Office 2016(Outlook)
Description
Skype Meeting Add-in for Microsoft Office 2016
File Name
UCADDIN.DLL
Add-in CLSID
{A6A2383F-AD50-4D52-8110-3508275E77F7}
Provider
Microsoft Corporation
File Timestamp
1499940832
File Version
16.0.8326.2044
Office App
Outlook
Number of Devices
35

Change macro settings to view information in the readiness report

The report created by the Readiness Report Creator uses macros and active content to display the information in the report. Therefore, to see the VBA macro compatibility and the add-in readiness information in the report, you need to allow macros and active content in Excel. If macros and active content aren't enabled in Excel, you see a Getting started message on the Overview worksheet when you open the report. On that page are instructions on how to enable macros and active content. This can be as simple as clicking Enable Content in the Message Bar.

In some cases, you might not see the Message Bar and the Enable Content choice. This is most likely because Excel is configured to disable all macros without notification. You can check this setting by going to File > Options > Trust Center > Trust Center Settingsā€¦ > Macro Settings. There, in the Trust Center dialog box, you can change the setting to Disable all macros with notification. After you do that, choose OK to save the change and close the Trust Center dialog box, then choose OK to close the Excel Options dialog box, and then close the report file. When you open the report file again, you should see the Message Bar and the Enable Content choice.

If the macro settings choices are grayed out in the Trust Center dialog box, an administrator has configured these settings by using Group Policy and the settings can't be changed manually. In this case, the simplest solution is to open the report file on a different computer where the macro settings for Excel allow you to enable macros by selecting the Enable Content choice in the Message Bar.

For more information about macro setting choices, see Enable or disable macros in Office files.

Possible steps to take for add-ins classified as "Unknown" or "Insufficient data"

If an add-in is classified as "Unknown" or "Insufficient data" this means that Microsoft doesn't yet have sufficient information regarding the add-in to provide a readiness status. If this is an add-in that is business critical for your organization, you can do the following:

  • Contact the software provider who developed this add-in to see if the add-in is supported for Office 365 ProPlus. Also, you can request that your software provider list the add-in's support for Office 365 ProPlus on the Ready for Windows site. By listing the add-in, the software provider can make the add-in's support status for Office 365 ProPlus available to other enterprises.

  • Contact us at ReadyForOffice@microsoft.com. We'll do our best to add the readiness status of the add-in to our database. Please provide as much information about the add-in as possible including, but not limited to, the following:

    • Friendly name

    • File version

    • Software provider

    • Download link, or any details on how to download and install the add-in.

    • Other details, such as the type of add-in, which Office app the add-in is used with, the Prog ID, or the CLSID.