Skip to main content
Matrix42 Self-Service Help Center

Converting Add-On to Configuration Package


Starting from DWP Release 10.2 Update 2 or higher any Add-On can be converted to a Configuration Package and installed to the necessary environment even without access to the App Server. 

Every Add-On has its unique file set and folder structure and its implementation, testing, and installation used to include more steps than it required now with the introduction of the Configuration Packaging technology.

The Add-On that is converted to the Configuration Package can be installed directly from the user interface with Install Package Action introduced in 10.0.2 release version. 

10.0.1 version also supports Configuration Package installation with cmdlets PowerShell scripts. This approach additionally requires Service Account credentials. 

In order to be converted into a Configuration Package, you need to make some manual adjustments of the folder and file structure of the previously developed Add-On.

To convert the Add-On:

  • Unarchive the Add-On to a folder;
  • Convert the Add-On manually to a Configuration Package;
  • Archive the converted package;
  • Run installation of the Configuration Package.

File Structure 

Any package or add-on that has been developed before the introduction of the Configuration Packaging technology should be adjusted manually and comply with the standard Configuration Package file structure:




Create the folder structure as shown on the provided example and copy the files from the existing add-on to the appropriate folders as follows:

The Add-On content differs from one package to another and does not necessarily include every type of the enumerated files and folders. If the Add-On does not have a certain file or folder just skip it.  

  • Assemblies folder is intended for binaries like .dll files and .pdb files included to the following folders:
    • bin
    • svc
    • ServiceRepository
      If the source package has a folder with binary files you can copy it as is to the target package as a sub-folder of the Assemblies.  
  • Files:  
    • Reports are delivered as files. You can add as many reports as necessary and place them in one folder on the same level, or use nesting folders if you need a multi-level report structure:
      For localized versions of a specific report add the sub-folders with the language codes.
    • Web: add other files that do not belong to any of the available sections of the Configuration Project, like images or icons that are not a part of the Workspaces, configuration files, other special files, like .XML, etc.
    • WM includes all front-end workspaces resources (like Javascript libraries, CSS, images, etc.) required for building user interfaces in Matrix42 platform. For more details see Front-End Workspaces page.
  • Install folder is intended for a set of files that contain the actual changes stored as schema scripts  and applied to the system by the project install;
  • install.xml includes a set of changes and schema scripts order in which they will be applied during the package installation process. Rename the existing file from the add-on to install.xml and place it as a separate file in the main folder of the converted configuration package;
  • Scripts folder can be added optionally for a PowerShell script and SQL script that are applied after the schema scripts from the Install folder. For package components installation sequence see Package Installation page
    The PowerShell script and SQL script are equivalent to the data that can be added in Install section of the Configuration Package Setup Directives
  • package.json is a descriptor of the package with the basic information that is used during installation/uninstallation of the Configuration Project on another environment.

package.json file is a mandatory file of the package that is created and filled out manually.

PowerShell scrips for Workflows publishing are no longer needed, as the workflows delivered with the package are published automatically both for AppFabric and Worker workflow engines.

Package.json content

File example:

  "Id": "e11c11c1-1a22-c333-4d44-05d55a55c55b",
  "Vendor": "Matrix42 AG",
  "Name": "HR Portal",
  "Description": "Payroll",
  "Version": "1.0",
  "LastUpdatedDate": "2020-06-15T11:30:00", 
  "SetupDirectives": {
    "MaintenanceMode": false,
    "RecycleWebApplication": false,
    "RestartM42WindowsServices": false
  "Prerequisites": {
    "MinimalRequiredProductVersion": "10.0.1",
    "DependentPackages": [
        "Id": "ca87d770-d3d8-c6ba-07d5-08d871cdbcb0",
        "MinimalRequiredVersion": "2.0",
        "PackageName": "HR Portal",
        "Vendor": "matrix42 AG"

package.json includes:

  • Id: the unique identifier of the package. Generate GUID and add it to the file;
  • Vendor: identifies the author or the company that developed the package, in case of DWP it's "Matrix42 AG";
  • Name of the package;
  • Description: a short description of the package that is shown before the installation on the package upload page;
  • Version: package version with major and minor numbers, for instance: 2.1;
  • LastUpdateDate requires the year, month, date, and time in the following format: 2020-06-15T11:30:00;
  • Setup directives allow configuring additional properties that can be required for successful package installation. For more details see Setup Directives section.
    • MaintenanceMode defines how the package installation is run:
      • true: the application is no longer available for the users and the package installation will be run in the maintenance mode; 
      • false: use this option to minimize the system downtime and make the installation unnoticeable for the current users. 
    • RecycleWebApplication: 
      • true: set this option to restart the M42Services that are necessary for running the website;
      • false: use this option to skip this step;
    • RestartM42WindowsServices directive can restart the HostCommon, HostCommon x86, Scheduler, Data Gateway, and Worker services:
      • true: set this option to restart the enumerated services;
      • false: use this option to skip this step.
  • Prerequisites: optional section, where you can define system version and dependent packages. Specify this data as follows:
    • MinimalRequiredProductVersion: the minimum version of the Digital Workspace Platform that allows the installation of the edited package;
    • DependentPackages: information about the packages that must be installed before running the installation of the package we are currently editing, otherwise the package installation is not possible. You can retrieve this data from the package.json file of the packages that you would like to add as dependent:
      • Id: the unique identifier of the dependent package;
      • MinimalRequiredVersion: the minimum required version of the dependent package that must be already present in the system before running the installation of the currently edited package;
      • PackageName: name of the package;
      • Vendor: name of the author or the company that developed the package.

For more information about the package components installation sequence see Package Installation page.

Package Installation

To install the converted add-on, proceed with the instructions on the Configuration Package installation based on DWP version:

  • Was this article helpful?