The Readiness Toolkit for Office Add-ins and VBA can help you identify compatibility issues with your VBA macros and add-ins that you use with Office. It has been used by over a thousand enterprise customers to help assess Office compatibility prior to upgrading to Office 365 ProPlus.
We have heard from some customers that they’d like more detail on how the Readiness Toolkit scans files, and what data is being sent when they generate an advanced report. This information is already available in the Readiness Toolkit documentation (aka.ms/ReadinessToolkit), and this article aims to share this information in an easier to digest manner.
This article will cover two key topics, (1) how the Readiness Toolkit scans files for incompatible VBA code and (2) what information is sent to Microsoft when the user creates an advanced report.
(1) Scanning files
When scanning files for incompatible VBA macro code, the Readiness Toolkit goes through a three-step process, (1) check file extension, (2) scan VBA project (3) check ObjectModel calls and references.
1.1 Check file extension
The toolkit first checks the extension of the document. Every Office document is assessed for compatibility, but only Office documents that contain macros are passed on to the scanning component. For a full list of Office documents assessed, see the following link. Office documents that don’t contain macros are assessed and classified as compatible, with Office documents containing macros being passed to the scanning component for further analysis.
1.2 Scan VBA project only
Office documents contain several components. The content, the metadata, the VBA project and more. The toolkit only scans the VBA project, selected in the image. It does not scan the contents of the document. This is a read-only scan, the Readiness Toolkit does not write any changes to the files. Given that only ~5% of documents contain VBA projects, this means that most files don’t enter this scanning process.
Note: For modern format files (OOXML), you can rename the file extension to .zip and unzip the resulting file to view the structure of the Office document directly.
1.3 Scanning VBA code
The toolkit then parses the VBA code within the VBA project and compares each method and property call against a list of known changes in the Object Model, recording each statement that has potential compatibility issues, along with guidance and the severity of the issue identified. This information is written out in a vba.json file.
For example, in the code above, “value = instance.DocumentMapPercentWidth” and “instance.DocumentMapPercentWidth = value” are flagged with the severity “Limited remediation required” and the guideline “Window.DocumentMapPercentWidth property is no longer available. (Word 2013, Outlook 2013)”.
Scanning typically takes around half a second per file that contains a VBA project, but this can vary based on the size of the VBA project and whether the file is being read locally or across a network.
(2) Advanced report
The Readiness Toolkit is an on-prem solution, and it is completely optional to send information to Microsoft in relation to the add-ins that are installed. If you choose to create an advanced report, some information about your VBA macros and add-ins is sent to Microsoft to allow us to provide compatibility information. For example, add-in metadata such as the name, publisher and version are sent to the service so that compatibility information for this add-in can be fetched and displayed in the report.
Information on VBA macros and add-ins sent to Microsoft can also give us visibility into compatibility issues users are facing and help us make product improvements. For example, a count of how many files had issues and the specific compatibility rule that had been broken is sent, allowing us to make product improvements such as adding 64-bit support for mscomctl.ocx, allowing users working in 64-bit versions of Office to create, edit, and open macro files containing the Common Controls, released in build 1707 (learn more).
More details on the information that is sent to Microsoft when creating an advanced report can be found in the official Readiness Toolkit documentation (learn more).
Side note: To protect the privacy of users and to help prevent revealing sensitive information, the Readiness Toolkit allows you to conceal the file paths and names of documents identified during a scan. This is covered in the Readiness Toolkit documentation (learn more).
Conclusion
This article has given more details on how the Readiness Toolkit scans documents and what data is collected by the Readiness Toolkit to provide compatibility information in the Readiness report.
If you have any further questions about the Readiness Toolkit, please post below or get in touch via ReadyforOffice@microsoft.com and our team will be sure to help.