There are two options for the Configuration Package installation: upload package and run installation via the user interface or run the installation directly on the application server with the PowerShell script.
Only the Administrator can run the package installation.
Install Package Action
To install Configuration Package via user interface proceed to the Administration application → Extensions → Installed Packages → click Install Package action:
Uploaded and ready for installation Configuration Package details preview
- Upload the archive of Configuration Package in the suggested field;
- Wait for the Configuration Package details preview, depending on a package size the upload may take a while.
- Handle warnings, if there are any;
- Click Start Installation. The Installation Progress view shows more details about the current installation processing stage and occurring errors.
- Click Finish to complete the package installation.
The page reloads and the installed package is available in the system.
Configuration Package Installation Progress view: successfully finished installation example
Depending on the package, there might be warning messages before you can actually run the Configuration Package installation
System downtime confirmation
If the Setup Directives differ from the default values the system informs that the package installation may cause the system downtime. Confirm the warning message and proceed:
Only one package installation can be running at the same time in the same environment.
If another Administrator user tries to start the package installation the following message is shown:
For the packages with system version dependencies or dependent packages the following messages are possible:
Install the missing packages first and then proceed with the current Configuration Package installation.
For more details see Configuration Package Prerequisites settings.
Installation with cmdlet PowerShell script
To install the package:
- Upload the package archive to the application server;
- Enable maintenance mode (optional, depending on the package);
- Run the PowerShell script as an Administrator to install the package:
Import-Module "<PathToYourInstallation>\bin\matrix42.maintenance.cmdlets.dll" -force $Credentials = Get-Credential New-WMConfigurationSession -Credentials $Credentials Enable-WMMaintenance #Switching Maintenance Mode On (optional) Install-ConfigurationPackage -File "<PathToYourPackageZipArchive>" -Log packages.log -ExitOnError Disable-WMMaintenance #Turning Maintenance Mode Off (optional)
For more information see also Interactive Usage of Powershell page.
The successfully completed Configuration Package installation may look as follows:
Installation with API
It is also possible to install a Configuration Package using API
For more information see Configuration Package Installation API page.
Package Components Installation sequence
Package Installation regardless of the installation type (via user interface or PowerShell script) involves standard for the Configuration Packaging processing stages.
The overall sequence includes the following steps:
- Check Configuration Package Prerequisites compliance
- Enable maintenance mode
- Stop services
- Files copy (including assemblies)
- Applying Schema Scripts
- Applying SQL script
- Applying PowerShell script
- Automatic compliance rule processing
- Automatic workflow publishing
- Report deploy
- Service restart
- Application pool recycle
- Remove maintenance mode
Not all steps are mandatorily applied for your specific Configuration Package installation. Depending on the Configuration Package content and settings, like Setup Directives, some steps can be skipped or omitted.
Installation Troubleshooting & Recovery Console
For cases when the package installation via the user interface fails, analyze and fix the issue using the information provided in the installation progress view and click Retry:
Use Cancel to abort the package installation.
Cancel action uses the scripts available in the package and may lead to one of the following results:
- Package has all necessary scripts: Cancel reverts the changes applied by the package and rollbacks the system to the previous state, either removes the package entirely in case of the new package installation or reverts to the previously installed package version in case of package update. This scenario is feasible when the Configuration Package is developed using the low-code platform that automatically generates all necessary scripts for the rollback procedures.
- No scripts to run: the uploaded for installation package has been converted manually and is missing some of the required folders and uninstallation scripts or they are misconfigured and do not include the PackageVersion attribute, unregister scripts, etc.
A complete list of necessary files, folders, and their structure is available on the Converting Add-On to Configuration Package page, see sections:
Installation recovery console
For the cases when the package installation runs in the maintenance mode and the installation fails due to some reason, the system provides an installation recovery console where the issues can be analyzed and the package installation can be canceled.
The installation recovery console opens automatically for the system administrators when the package installation running in the maintenance mode has failed and the system is not available for other users.
The package installer recovery console lists all packages that have been installed on the current environment and the package installation in progress:
The same as for the Install Package action, you can analyze and fix the issue using the information provided in the installation progress view and click Retry or click Cancel to abort the installation and turn off the maintenance mode.
The installation recovery console can also be accessed by the Administrator by adding
/wminstaller to the application URL.
Any user with Administrator permissions can access the recovery console and retry or cancel the package installation started by other Administrator on the current system environment.
Click on the package to see details:
Configuration Item Permissions is not applied immediately
Installing the Configuration Package does not apply immediately the delivered Configuration Item permission changes for all currently logged in users. It could lead to misbehavior of the artifacts installed with the Package. To solve the issue the user just needs to re-login.
The Installed Packages are listed on a dedicated page of the Administration application:
Click on the Configuration Package object for more details:
The installed package preview includes such details as the package name, installed version, vendor, installation date, last update, and description.
Optionally, the installed packages might have dependent packages and vice-versa:
- Uninstall Package: removes the changes that were added to the system when the Configuration Package was initially installed.
- Export: Export the Configuration Project data in a .zip file.
- History: View the history of all the Configuration Project related transactions. You can filter the transactions by date, attribute, user and/or transaction type.