Skip to main content
Matrix42 Self-Service Help Center

Configuration Package Installation


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 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

  1. Upload the archive of Configuration Package in the suggested field;
  2. Wait for the Configuration Package details preview, depending on a package size the upload may take a while.
  3. Handle warnings, if there are any;
  4. Click Start Installation. The Installation Progress view shows more details about the current installation processing stage and occurring errors.
  5. 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

Warning messages

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:


Concurrent installations 

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:


Prerequisites compliance

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.

Installation with cmdlet PowerShell script

To install the package:

  1. Upload the package archive to the application server;
  2. Enable maintenance mode (optional, depending on the package);
  3. 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:

  1. Check Configuration Package Prerequisites compliance
  2. Enable maintenance mode
  3. Stop services
  4. Files copy (including assemblies)
  5. Applying Schema Scripts
  6. Applying SQL script
  7. Applying PowerShell script
  8. Automatic compliance rule processing
  9. Automatic workflow publishing
  10. Report deploy
  11. Service restart
  12. Application pool recycle
  13. 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.

In the future release, the Cancel button will revert the changes applied by the package and rollback the system to the previous state.

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:


Installed Packages

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:

  • Was this article helpful?