Skip to main content
Matrix42 Self-Service Help Center

Converting Add-On to Configuration Package

Overview

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:

 

CP_folder_structure3.jpg 

 

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

Uninstall scripts

It is highly recommended to avoid creating the entire set of uninstallation scripts manually. Use the automated script generation approach instead, since all necessary scripts for installation and uninstallation are created automatically during the Configuration Project Development stage.

The set of the below-described files is necessary for the Uninstall Package action  and Cancel Package Install action proper functioning:

  • Uninstall folder is intended for files that are grouped as a set of scripts for uninstall of FilesLayoutsWorkflows, Reports, and other Objects that modify the user interface of the system. The folder does not include Schema changes (Configuration Items and Data Definitions). The files in the Uninstall folder files are actually Schema Scripts of a .del type;
  • uninstall.xml contrary to install.xml, includes a set of changes and schema scripts order in which they will be applied during the package uninstall process. The file includes scripts from the Uninstall folder only;

Unregister Scripts in SchemaScript database table

Additionally, Uninstall folder must include .post scripts that remove information about the scripts that had been registered in the system during the Configuration Package installation or update. As the SchemaScript database table keeps track of all scripts that have been run in your system and makes it impossible to run and register them more than once, this step allows you to reinstall the Configuration Package on the same environment after uninstallation, and thus register the appropriate scripts in the SchemaScript database table.

To unregister scripts you need to remove the corresponding records from the SchemaScript database table as follows:

/*1.0*/DELETE FROM SchemaScripts WHERE Major = 2 AND Minor = 1 AND Build = 5 AND Type = 'dat' AND 
Name = '624749e7-058f-cf41-645e-08d884bf6e12_tst_PDRContentWidgetTemplateType_test Preview'
/*2.0*/DELETE FROM SchemaScripts WHERE Major = 2 AND Minor = 1 AND Build = 14 AND Type = 'dat' AND
Name = '624749e7-058f-cf41-645e-08d884bf6e12_test_PDRNavigationItemType'

It is essential to specify the package version at the beginning of each line before the delete statement:  /*1.0*/

It consists of a major and minor version and denotes when the change had been introduced in the package. The version in the specified format is also crucial for the proper functioning of the Cancel option during package installation and update.

Create separate .post files for the corresponding folders, for instance:

Folder File name File content
Uninstall UnregisterInstallScripts_Sobu.post  SQL delete statements for changes related to FilesLayoutsWorkflows, Reports, and other Objects that modify the user interface of the system.

Package.json content

File example:

{
  "Id": "e11c11c1-1a22-c333-4d44-05d55a55c55b",
  "Vendor": "Matrix42 AG",
  "Name": "HR Portal",
  "Description": "Payroll",
  "Version": "1.0",
  "RequiredLicenses":"M42HrPortal,M42TimeTracking,M42DigitalWorkspacePlatformSubscription",
  "LastUpdatedDate": "2020-06-15T11:30:00", 
  "MigratedPackage": true,
  "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;
  • RequiredLicenses: optional field for the name of the license certificate that is required for the package installation. You can skip this property, add one or multiple required certificates. The value for this property corresponds to the <product name=" " /> value specified in the license certificate.

Use Cases

  1. Extending existing products: your package extends the functionality of the existing product or subscription, for instance, your package adds new Actions or Layouts to the Service Desk and therefore the new package requires a Service Desk license certificate. The new package can be installed, but it will not function without the required license.
  2. Licensing a Configuration Package: the new package requires its own license and has a properly designed LicensedItems.xml file as a part of the package archive. For more details on how to structure the LicensedItems.xml file see Licensing a Configuration Package Extension section of the Product Licensing page.

RequiredLicenses Options:

  • not set: allows to install and use the package without license certificate;
  • specified: specify the product name(s) for the required licenses or the name of the required subscription, for instance
    • the package requires only one subscription:
      "RequiredLicenses":"M42DigitalWorkspacePlatformSubscription",
    • or a license certificate for a stand-alone product or custom package:

      "RequiredLicenses":"M42ConfigurationPackaging",

 

RequiredLicenses Syntax: use the following syntax to manage multiple required licenses

Syntax Description Example
, all listed certificates are required to show the installed Package as valid
"RequiredLicenses":"M42TimeTracking,M42ConfigurationPackaging"
& all listed certificates are required to show the installed Package as valid
"RequiredLicenses":"M42TimeTracking&M42ConfigurationPackaging"
| at least one of the enumerated certificates is enough to show the installed Package as valid
 
"RequiredLicenses":"M42TimeTracking|M42ConfigurationPackaging"

Combine the syntax for advanced cases:

"RequiredLicenses":"M42TimeTracking&M42ConfigurationPackaging|M42DigitalWorkspacePlatformSubscription"

In this example, required licenses are both M42TimeTracking and M42ConfigurationPackaging or only M42DigitalWorkspacePlatformSubscription is enough.

& has higher priority in complex expressions.

In the following example, required licenses are only M42TimeTracking or both M42ConfigurationPackaging and M42DigitalWorkspacePlatformSubscription:

"RequiredLicenses":"M42TimeTracking|M42ConfigurationPackaging&M42DigitalWorkspacePlatformSubscription" 

Licensing Status of the package can be previewed on the Installed Packages page

  • LastUpdateDate requires the year, month, date, and time in the following format: 2020-06-15T11:30:00;
  • MigratedPackage needs to be added in case Addon (CustomizingInstaller package) was available for customer installations before. By adding that flag, update to Configuration Package will be supported
  • 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?