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. 

In order to be converted into a Configuration Package, you need to make some manual adjustments to 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:

• Assemblies folder is intended for binaries like .dll files and .pdb files included in 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, and 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 the 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.

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

/*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'

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
  },
  "Apps": [{
        “Name”: “{app_name}”,  e.g. “workflow”
        “Url”:  “https://xxxx/{version}”,
        "StartPage": "{start page name}", e.g. "index.html",
        "STS": [
            {"clientid": "{OAUTH id}", "scope":"{OAUTH scope}", "redirecturl": "{redirect url}"}
        ]
      }
   ],
  "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

"RequiredLicenses":"M42TimeTracking,M42ConfigurationPackaging"

"RequiredLicenses":"M42TimeTracking&M42ConfigurationPackaging"

"RequiredLicenses":"M42TimeTracking|M42ConfigurationPackaging"

Combine the syntax for advanced cases:

"RequiredLicenses":"M42TimeTracking&M42ConfigurationPackaging|M42DigitalWorkspacePlatformSubscription"

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

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

"RequiredLicenses":"M42TimeTracking|M42ConfigurationPackaging&M42DigitalWorkspacePlatformSubscription" 

• LastUpdateDate requires the year, month, date, and time in the following format: 2020-06-15T11:30:00;
• MigratedPackage needs to be added in case Add-on (CustomizingInstaller package) was available for customer installations before. By adding that flag, update to Configuration Package will be supported;
• Apps: the list of the Single Page Applications deployed by the package.
  • STS: Provides an option to register dedicated OAUTH clients for the SPA purpose. On installation the configured clients are dynamically added to "Matrix42.Auth.STS.dll.config"
• 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 a 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.

Package Installation

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

• for 10.0.2 use Install Package Action;
• for 10.0.1 use cmdlets PowerShell scripts.