Updating

A new version comes as the same release package as the first installation (Installation). An update replaces the program files only. These stay as they are:

• appsettings.json (your configuration);
• App_Data (settings made in the app, dashboard history, API clients and their audit log);
• the log folder.

The update takes the app offline for a minute or two. Afterwards the app reads your tenant again, as after any restart; scan results are gone and must be run again (Data and cache).

Before you start

1. Read the release notes of the new version, if any, for new permissions, modules or settings.
2. Extract the package on the server and unblock it:

Unblock-File C:\Temp\IntensiveReports-<version>.zip
Expand-Archive C:\Temp\IntensiveReports-<version>.zip -DestinationPath C:\Temp\IntensiveReports-new

3. Back up appsettings.json and App_Data (Operations).

Install the new version

In PowerShell as administrator. Change the paths to yours.

$Site = 'D:\Sites\IntensiveReports'
$New  = 'C:\Temp\IntensiveReports-new\app'

# 1. Keep a copy of the current program files for a rollback
robocopy $Site "$Site.previous" /MIR /XD App_Data logs /XF appsettings*.json app_offline.htm

# 2. Take the app offline: ASP.NET Core stops the app while this file exists
Set-Content "$Site\app_offline.htm" '<!doctype html><title>Updating</title><p>IntensiveReports is being updated. Please try again in a few minutes.</p>'
Start-Sleep -Seconds 15

# 3. Copy the new version. /MIR removes files the new version no longer has;
#    App_Data, logs, appsettings*.json and app_offline.htm are left alone.
robocopy $New $Site /MIR /XD App_Data logs /XF appsettings*.json app_offline.htm

# 4. Bring the app back
Remove-Item "$Site\app_offline.htm"

robocopy exit codes 0 to 7 mean success; 8 and above mean that files could not be copied. If step 3 reports locked files, the app had not stopped yet: wait a little longer and run step 3 again. Always do step 4, also after a failure, or the site stays offline.

Note

The package never contains appsettings.json, so an update cannot overwrite yours. If a new version adds settings, the release notes and the new appsettings.template.json name them; add them to your file by hand.

After the update

1. Run the permission script again. It is safe to repeat and adds only what new reports need:

   .\setup\Grant-IrPermissions.ps1 -AppId <application-client-id>

   Use the same switches as at installation (for example -IncludeComplianceAdmin).

2. If the release notes say so, update the PowerShell modules with .\setup\Install-IrModules.ps1. Do not update the Exchange Online module on your own between releases (Troubleshooting).

3. Open the site. Pages fill in as the data loads.

4. As an administrator, open PowerShell Diagnostics (/PsDiagnostics): no warm-up errors, and Run probe connects.

5. Open Settings > Data & cache: no data source shows an error.

6. Open one report per workload you use.

Roll back

If the new version does not work, put the previous program files back:

$Site = 'D:\Sites\IntensiveReports'
Set-Content "$Site\app_offline.htm" 'IntensiveReports is being updated.'
Start-Sleep -Seconds 15
robocopy "$Site.previous" $Site /MIR /XD App_Data logs /XF appsettings*.json app_offline.htm
Remove-Item "$Site\app_offline.htm"

If the new version had already changed settings, restore App_Data from your backup as well.