Skip to main content
Matrix42 Self-Service Help Center

Configuration Package Installation

Overview

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: 

Install_Package_action.png

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.

package_installation_progress.png

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:
CP_installation_warning.png

 

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:

CP_running_installation.png

Prerequisites compliance

For the packages with system version dependencies or dependent packages the following messages are possible:

CP_install_version.png

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:

CP_PS_cmdlet.png

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

Retry

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:

CP_install_fail.png

Use Cancel to abort the package installation.

Cancel

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.

Technical implementation of the revert mechanism depends on the PackageVersion attribute used in the Schema Scripts and unregister scripts files.

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:

CP_recovery_console.png

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:

CP_installed_package_console.png

Known Issues

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. 

Installed Packages

The Installed Packages are listed on a dedicated page of the Administration application:

 CP_installed_packages.png

 

Click on the Configuration Package object for more details:

CP_dependent_packages.png

The installed package preview includes such details as the package name, installed version, vendor, installation date, last update, and description.

Dependencies

Optionally, the installed packages might have dependent packages and vice-versa:
CP_installed_package_depends_on1.png

Actions

  • 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. 
  • Was this article helpful?