While the upgrade procedure is the subject of the W823 Identity Panel Upgrade Workshop as part of the Administrator Knowledge Pack, this article describes the process in more detail as a reminder for those who have already attended this training.
Hosted Implementations
For cloud implementations, SoftwareIDM must firstly be engaged to update the hosted App Service. This can be done by submitting a support ticket with the SoftwareIDM Service Desk.
Once the App Service is upgraded, follow the step-by-step instruction for hosted environments below.
For on-premises upgrades please see Upgrade Identity Panel.
API-driven upgrade
There are two ways that upgrade files can be obtained from Identity Panel.
Both endpoints require an authenticated GET request with the Scheduler license key and Write|JsonSettings data permission.
1. Download Panel Tools Executable
Perform the following steps to interactively upgrade an instance of Panel Service (after the Identity Panel App itself has been ugpraded) for each Panel Server host:
-
Disable the Identity Panel Scheduler
- The upgrade process must only be initiated with the scheduler in a disabled state.
- To disable the scheduler so that schedules are not run interactively, navigate to Settings / Environment Settings / Environment Variables, deselect the Enabled checkbox and Save (floating toolbar)
- Remotely connect to the Panel Service host server over RDP
- Open a local browser on your host server and navigate to Settings / Install Service
- Click on the Download Installer button to download the self-extracting executable (e.g. PanelTools or PanelTools(1) if a previous download already exists).
- Run the self-extracting installer as Administrator to create a local PanelTools subfolder:
- Open a new CMD console in the identity of the Identity Panel service, using the Run As... option.
- You can obtain this identity by first inspecting the Services console
- You will require the password before proceeding
- Run ServiceSetup.exe from the installer-created subfolder
- Follow the instructions displayed on the screen, e.g.
Note: if you wish to override any of the default installation options (e.g. service name, program folder location, etc.) you must run ServiceSetup --advanced.
IMPORTANT: this process should only be performed by a person trained in the installation of Identity Panel.
Download Process Explained
The invoked endpoint /api/tenant/tools returns a file download of the Panel Tools installer package.
A GET request to this endpoint with the required verification token returns a result with a Content-Disposition header value of: "attachment; filename=PanelTools.exe", and a Content-Type of "application/octet-stream".
The body payload will be an SFX package produced by 7-zip containing the setup helper and associated files and dlls for installing Panel Service.
2. In-place Upgrade via Scheduler
This is the preferred method, and requires the configuration of a Schedule (see Maintenance Tasks below).
In-place Process Explained
For this method, a separate endpoint is used to facilitate in-place automated upgrade of Panel Tools.
The general method of the upgrade is for an Identity Panel admin to run an upgrade step via the scheduler. If the local Panel Service reports a different version number from the web application the in-place upgrade executes with the following steps:
- Download upgrade files to a temporary folder and extract the zip archive
- Rename existing local .dll, .exe, and .pdb files to append .upgrade
- Copy new dlls into the Panel Tools directory
- Start a new cmd process to execute the "net restart SoftwareIDM.PanelService" command
The endpoint for new dll files is /api/tenant/toolsupgrade. This endpoint enumerates all files in wwwroot\files\paneltools and wwwroot\files\paneltools\lib with a .dll, .exe, or .pdb extension and creates an in-memory zip stream.
NOTE: these files may not be downloaded directly as static files because the .NET static middleware does not allows files with these extensions to be requested.
The resulting zip stream is returned with a Content-Disposition of "attachment; filename=upgrade.zip" and Content-Type of "application/octet-stream".
Maintenance Task (with Upgrade step)
Best practice is to configure a Schedule to allow for the upgrade to be performed remotely without the need of remotely connecting to the Panel Service host over RDP. This will enable an in-situ upgrade to be initiated via the Identity Panel App, but only after the App itself has been upgraded:
If not already configured, the above schedule can be deployed as follows:
- Save the below JSON to a file on your local PC, e.g. MaintenanceSchedule.json
- Open a browser on your desktop and navigate to Settings / Schedules
- Click on the Upload button in the floating toolbar, and click Browse to select your saved file:
- Click OK to import the default schedule.
- Click the > button to expand the Maintenance Tasks strip and check that the various step settings are as required.
- Make any necessary amendments - e.g. adding any Silos to Reset on the Server to Reset strip.
- Click Save on the floating toolbar to commit any changes.
{
"Data": [
{
"$type": "SoftwareIDM.PanelModel.Models.Schedule, SoftwareIDM.PanelModel",
"Id": "01a9d82f-2ad5-4f40-90b9-5b0da3b853d2",
"Name": "Maintenance Tasks",
"Enabled": true,
"Description": null,
"Tags": null,
"Times": [],
"Steps": [
{
"$type": "SoftwareIDM.PanelModel.Models.Steps.ToolsUpgrade, SoftwareIDM.PanelModel",
"PreferredSchedulers": [
"Panel"
],
"Name": "Upgrade Panel Service on Panel",
"ConditionRule": "",
"SkipRule": "",
"PauseOnCondition": false,
"ASync": false,
"Timeout": "",
"ManualLocks": null,
"RemoveDefaultLocks": false
},
{
"$type": "SoftwareIDM.PanelModel.Models.Steps.RestartPanelService, SoftwareIDM.PanelModel",
"PreferredSchedulers": [
"Panel"
],
"Name": "Restart Panel Service on Panel",
"ConditionRule": "",
"SkipRule": "",
"PauseOnCondition": false,
"ASync": false,
"Timeout": "",
"ManualLocks": null,
"RemoveDefaultLocks": false
},
{
"$type": "SoftwareIDM.PanelModel.Models.Steps.UniqueIndexStep, SoftwareIDM.PanelModel",
"Label": "Unique Index Processing",
"ConditionRule": "",
"SkipRule": "",
"PauseOnCondition": false,
"ASync": false,
"ManualLocks": null,
"RemoveDefaultLocks": false,
"PreferredSchedulers": [
"Web"
],
"Name": "Unique Index Processing",
"Timeout": ""
},
{
"$type": "SoftwareIDM.PanelModel.Models.Steps.ApplyJoinStep, SoftwareIDM.PanelModel",
"Label": "Apply Join Rules",
"Silo": "",
"ConditionRule": "",
"SkipRule": "",
"PauseOnCondition": false,
"ASync": false,
"ManualLocks": null,
"RemoveDefaultLocks": false,
"PreferredSchedulers": [
"Web"
],
"Name": "Apply Join Rules",
"Timeout": ""
},
{
"$type": "SoftwareIDM.PanelModel.Models.Steps.ReindexStep, SoftwareIDM.PanelModel",
"Label": "Reindex Search",
"Silo": "",
"Truncate": true,
"ConditionRule": "",
"SkipRule": "",
"PauseOnCondition": false,
"ASync": false,
"ManualLocks": null,
"RemoveDefaultLocks": false,
"PreferredSchedulers": [
"Web"
],
"Name": "Reindex Search",
"Timeout": ""
},
{
"$type": "SoftwareIDM.PanelModel.Models.Steps.ResetScanCache, SoftwareIDM.PanelModel",
"PreferredSchedulers": [
"Panel"
],
"Silos": [
],
"Name": "Reset Silo Cache 0d972993-909f-47d8-a563-032f68ae302c, cc724ad3-4891-46a1-859c-6f04ca5976e4 on Panel",
"ConditionRule": "",
"SkipRule": "",
"PauseOnCondition": false,
"ASync": false,
"Timeout": "",
"ManualLocks": null,
"RemoveDefaultLocks": false
}
],
"Security": {
"$type": "SoftwareIDM.PanelModel.Models.ScheduleSecurity, SoftwareIDM.PanelModel",
"Invoke": null,
"Edit": null
},
"Priority": "Normal",
"Exclusive": true
}
],
"Count": 1
}
Comments
0 comments
Please sign in to leave a comment.