Upgrade Readiness Client Configuration

Hello, again! I am back and this time, we will look at how to start data collection for the Windows 10 Upgrade Readiness solution. This part assumes that you have a working Operations Management Suite (OMS) subscription and the Upgrade Readiness solution has been configured as highlighted in my previous post.

For client configuration, there are some key requirements that need to be met.

Operating System Requirement:  Upgrade Readiness can be used for clients running Windows 7, Windows 8 and Windows 8.1 only. Windows XP is not supported.

Patch Requirements:  The Windows 10 Upgrade Readiness solution uses telemetry to collect application details from clients. Because telemetry was not a built-in component on older operating systems, some patches need to be deployed to your clients. They install the framework needed for generating telemetry needed for Upgrade Readiness.

First, you need the Windows Compatibility Updates.

• Windows 7 RTM (and I do hope you’ve already upgraded your clients to SP1): KB2977759
• Windows 7 SP1: KB2952664
• Windows 8 and Windows 8.1: KB2976978

Next, you need the Windows Compatibility Definition update. This is common for Windows 7, Windows 8 and Windows 8.1.

• Windows Compatibility Definitions Update: KB3150513

Finally, if you want to capture telemetry on Internet Explorer to manage IE compatibility and Internet Explorer Enterprise Mode (IEEM), you need one more update to the telemetry components. Again, this is common for Windows 7 and Windows 8 and 8.1.

• KB3080149

Note: These patches are revised frequently as the backend cloud service evolves and as new capabilities are added. So, you might want to consider setting up auto approvals for these patches within your patching mechanism (SCCM, WSUS or 3^rd party patch management solution).

Firewall/Proxy Requirements:  For data to be sent out to your Upgrade Readiness solution, some firewall or Proxy exceptions might need to be added. Make sure access to the following URLs is not blocked.

• https://v10.vortex-win.data.microsoft.com/collect/v1
• https://settings-win.data.microsoft.com/settings
• https://vortex.data.microsoft.com/health/keepalive
• https://settings.data.microsoft.com/qos
• https://go.microsoft.com/fwlink/?LinkID=544713
• https://compatexchange1.trafficmanager.net/CompatibilityExchangeService.svc/extended

After adding the required exceptions some more work may be needed if your proxy servers are configured for user authentication. Review this blog post to get this configuration completed. Support for user authenticated proxy servers was added in December 2016.

Deployment Scripts – The last step before you start client configuration is getting the client deployment scripts. The scripts are available here.  Download and extract the scripts for configuring clients. There are two folders in the archive that you will download:

• Pilot: As the name implies, this is what you will use to manually configure a few clients for Upgrade Readiness. The purpose of the pilot scripts is to ensure the scripts are all working and data collection is also working.
• Deployment: The deployment folder is a slightly smaller set of files and there is no Diagnostics subfolder. These are used to automate the deployment process using SCCM or any other enterprise software deployment solution.

Pilot Deployment

The file structure in the Pilot folder would look like this. The two most important files are:

• ConfigScript.ps1
• RunConfig.bat

 

No modification of the ConfigScript.ps1 is required. The RunConfig.bat file allows you to capture the parameters you want to use. When you run the batch file, it passes the parameters to the PowerShell command to execute the script. Let’s take a quick look at the batch file.

For the commercialIDValue variable, use the “Commercial ID” that was generated when you setup your Upgrade Readiness solution. If you don’t have this, you can pull it out from your OMS workspace. Make sure there are no leading or trailing spaces in the value you provide. These additional whitespaces can cause issues and can slow down your rollout for Upgrade Readiness.

In the screenshot above, if you want to change the logPath variable to a different location, you can do that. The default location is C:\UADiagnostics and does not necessarily need to be changed. You don’t need to change the runMode variable.

Note: In the deployment folder, the logPath variable is not defined. You would need to provide either a network share or a local folder

The next settings we make will configure the logging mode and the level of logging. logMode helps define how you want to capture data that may be needed to troubleshoot the deployment. A value of 1 allows you to track issues as the script is executing and provides a log file that can be used for further troubleshooting if needed.

If you are interested in your IE site Compatibility Information you would want to set the AllowIEData to IEDataOptIn. Then set the IEOptInLevel to the define how much information is captured. The comments on the script explain what level of information will be collected for different IEOptInLevel values. 

When the script execution starts, it starts initial data collection by running the appraiser. If the appraiser is already running when you execute the deployment script the system will wait and retry running of the appraiser. The default number of retries on the script is 3. Usually this maximum retries value is sufficient, however if the script cannot start data collection by triggering the appraiser, setup will fail. You can also increase the number of retries, but in my experience this is not normally required. If you want to change the maximum number of retries, this is done by increasing the value on the NoOfAppraiserRetries variable.

The next section that we might need to change defines how the client will send data to the Upgrade Readiness solution. This is where you can configure a Proxy server.

• If you have a user authenticated proxy, you need to change the ClientProxy variable to User.
• If there is a system wide proxy, you need to change the ClientProxy to System. You might need to run the following command to ensure that the proxy configuration is correctly set:

                netsh winhttp import proxy source=ie

•  The default setting for ClientProxy is Direct. If there is no proxy server, you can leave this setting as it is.

 

With these settings defined, you can save and execute the batch file. On execution, you should see a PowerShell window pop-up where script execution progress will be displayed. The PowerShell window closes out as soon as the script execution completes. A return code of 0 from the batch file execution indicates that setup completed successfully.

Any other return code indicates that the client configuration failed to complete successfully. If there is a non-zero return value, it’s time to dig in to the log file that will be generated under the folder specified for the logPath variable. The file name will be generated with syntax like UA_yy_mm_dd_hh_mm_ss_GUID.txt. Information in this file should provide insights into the cause of the failure.

If your configuration was successful, you need to wait for a period of at least 48 hours before you start seeing information in the OMS workspace. Depending on how the system is being used, it might take longer for the data to start showing up.

Wider Deployment

If your pilot deployment works as expected and you see data being populated on your OMS workspace, you are ready to automate the deployment of the client on a wider scale using the files inside the Deployment folder. There is a RunConfig.bat file here (which is almost identical to the RunConfig.bat in the Pilot folder with a few minor changes). You will need to modify just like you modified the file under the Pilot folder and then package everything under the Deployment folder for package / deployment source files.

The configuration needs to run under the context of the System Account. If you are using SCCM for the deployment, this will happen automatically as the SMS Agent Host service is configured to run under System account by default. If you are using a 3^rd party mechanism, ensure that you run the deployment under the System account.

Tips

• Not configuring the ClientProxy variable correctly will cause the script to exit with a return code of 15. The following error will be shown in the log file. If you encounter a return code of 15, examine the ClientProxy variable and ensure it is correctly configured.

•  If you installed the pre-requisite client patches a long time ago (when they were first released, for example), you might see additional failures due to the Telemetry framework components being outdated. If that is the case, you will see a return code of 32. The solution for this is to reinstall the compatibility and compatibility definition update patches, as outlined above..

For other return codes and potential remediation actions, review the information outlined on: https://technet.microsoft.com/en-us/itpro/windows/deploy/upgrade-readiness-deployment-script

This wraps up the client data collection setup, I will be back soon with a post on how to make best use of the data that is collected by Upgrade Readiness.

Thanks

Nandan