Building Custom Packages¶
Each KX Platform package is a collection of entities stored as a set of XML files. These files can be imported into a Platform instance to populate it with the entities defined in the package.
The package XML files are organized into directories based on the entity type they represent. As well as the XML files there are 2 package manifest files which define the list of entities which are part of the package and also the name of the package in Control. There is often an optional XML file which contains the list of permissions to be set on each entity when importing into the Platform. Using the example of the DeltaStream package the files in questions are:
Packages should be named based on the solution they contain. Package names are typically camel case and there should be no spaces in the package name.
In order for a package to be installable via the Installation script it must follow a set structure.
Package - Naming convention¶
The product name for a package is the string before the first “_” in the package name. i.e. for
DeltaStream_4_5_0_200231082608.tgz the product name is
Note: All package config files (except version.txt) are based on the Product Name and it is important that these files are named correctly or else the install script will not find them in the package. The files required for a package and the naming conventions are described below.
KX Platform packages must be named as follows:
They must untar (
tar -xvzf <package>.tgz) into a directory with the following name:
tar -xvzf DeltaStream_4_5_0_200231082608.tgz DeltaStream_4_5_0_200231082608/
Package - Required files¶
This section describes the files which must be present in the package in order for it to be installed with the script.
|Version file||version.txt||Package directory|
|Install Config||CustomSolution.install.config||Package directory/install_config/profiles|
CustomSolution_4_5_0_200231082608/CustomSolution.cfg CustomSolution_4_5_0_200231082608/CustomSolution_export.cfg CustomSolution_4_5_0_200231082608/CustomSolution_permissions.xml CustomSolution_4_5_0_200231082608/version.txt CustomSolution_4_5_0_200231082608/install_config/profiles/CustomSolution.install.config
Package - Configuration options¶
Each package is required to have its own configuration file. This file defines at the bare minimum any dependencies for the package along with an optional list of environment variables to be written into the delta.profile.
The package configuration file should be named
<PackageName>.install.config and should be placed into the following directory structure inside the package:
The basic package file will contain one line which defines the package dependencies. The
CustomSolution is dependent on
DeltaStream being deployed. So the contents of the file would look like this:
cat install_config/profiles/CustomSolution.install.config DEP|DeltaStream
The package configuration file allows package specific environment defaults to be updated when deploying the package using the install script.
|Env Var type||Value||Notes|
|port||int||Default value for an environment variable which represents a port. The install script will check if the port is free|
|string||string||Any string which will be assigned to the environment variable.
Note cannot contain spaces
|dir||dir||Create a new directory which the environment variable will point to.
For a new directory to be created inside the delta-data directory then it should be specified as follows: DELTA_DATA/CustomSolution/hdb
Environment variable naming¶
Environment variables within a package should be named as follows:
For example Delta Control Port variable is named
The format of the configuration file should be as follows:
ENV | Variable Name | Variable Type | Variable Default | Update Option (0 or 1)
|ENV||Denotes that this line contains an environment variable definition|
|Variable Name||The name of the environment variable (this is written into delta.profile)|
|Variable Type||port, string or dir|
|Variable Default||The default value to be assigned to the variable|
|Update Option||0 - variable is not prompted for on deploy the default value is taken
1 - variable is prompted for during interactive installation (accept-defaults=0)
See example package configuration file for a dummy CustomSolution package below:
ENV|CUSTOMSOLUTION_TPLOGDIR|dir|DELTA_DATA/CustomSolution /tplog|0 ENV|CUSTOMSOLUTION_DEBUGPORT|port|2200|1 ENV|CUSTOMSOLUTION_DEBUGMODE|string|NO|1
Using the package configuration file above the user would be prompted only for the
CUSTOMSOLUTION _DEBUGNODE values during installation.
CUSTOMSOLUTION _TPLOGDIR would be created automatically inside the delta-data/ directory i.e.
Deploying Custom Packages¶
The KX Platform bundles can also be used to deploy a Solution or Custom packages.
These are packages which form part of a solution built on top of the KX Platform. The packages are typically listed in the package ordering lists inside the KX Platform install script (
In order to deploy solution packages they should be placed into the
packages/ directory inside the bundle prior to running the
These are packages which are not yet included inside the package ordering lists in the KX Platform install script (
Custom packages must have the same structure as Platform or Solution packages, They can be deployed by placing them inside the
packages/ directory in the bundle then adding the following to the install.config file (
scripts/install.config) prior to running the
The install config (custom-solution-package-list) should contain a comma separated list of package names minus any version information.
Once this has been configured the deploy can be run using
For more details on the available install options, see the Package List Options section of this guide.