How to Add a Custom Client Package to Refinery

What is a client package used for?

A client package in Refinery allows you to upload your own custom code to use it within the Refinery. This code works with both the API plugins and the internal process events. These features allow you to customize your Refinery installation to your own specific use cases without disrupting the functionality of the Refinery core code.

Installing a client package

The process for installing a client package is similar to that of the Delta/Platform packages. The easiest way to set up the client package is as follows:

Step 1 - connect to control

Start up the Refinery Installation and connect to Control.

Step 2 - create new package

To create a new package, follow the steps below:

  1. Navigate to the File tab.
  2. Create a New package.
  3. Enter a name, i.e. ClientPackage.
  4. Ensure the Base Directory points to the installation's package directory.
  5. Click Add.

Step 3 - create new user

To ensure the package installs correctly, it must have an associated entity. You can create either a real or dummy user for this purpose, by following the steps below.

  1. Right-click the newly created package on the left-hand tab.
  2. Click New > User.
  3. Assign a name and password
  4. Click Add, then Save on the right-hand side.

Step 4 - export package

To export your package, follow these steps:

  1. Open the Package Exporter by clicking the Tools tab on the top left of the screen.
  2. Check the box for Include Permissions.
  3. Click Export All.

This exports your package to your package directory (DELTA_PACKAGE_HOME) within your Refinery install.

Step 5 - set up folder structure

Add the following to your package: - install_config/profiles/ClientPackage.install.config - version.txt - A src directory (this is where your custom code is stored)

Rename the package to include a version number. The tree should look like this:

tree [DELTA_PACKAGE_HOME]/ClientPackage_0_0_1

├── ClientPackage.cfg
├── ClientPackage_export.cfg
├── ClientPackage_permissions.xml
├── install_config
│   └── profiles
│       └── ClientPackage.install.config
├── src
│   └── customCode.q
├── user
│   └── Dummy.xml
└── version.txt

Step 6 - add info to files

Add the following to their respective files:

ClientPackage.install.config

ENV|REF_CLIENT_PACKAGE|string|ClientPackage|0
DEP|

version.txt

product.name=ClientPackage
major.version=0
minor.version=0
incremental.version=1

Step 7 - tar package

Tar this package and add it to the Refinery package directory (KxRefinery(Finance)-5_X_X/packages/).

tar -czvf ~/KxRefinery(Finance)-5.X.X/packages/ClientPackage_0_0_1.tgz ClientPackage_0_0_1

Step 8 - add installation info

Add custom-environment-package-list=ClientPackage within the install.config that you use for installing/upgrading the Refinery.

Add ClientPackage to the DELTA_DAAS_SOLUTION_PACKAGES parameter within the install script (installKxPlatform.sh or installDeltaXML.sh).

Step 9 - run install script

Shut down your Refinery installation. Then, run the install script using either the Refinery CLI or the install script directly.

Step 10 - check installation was successful

Once the installation is complete, check that everything has been installed correctly by checking the delta.profile to see if export REF_CLIENT_PACKAGE=ClientPackage has automatically been added to the file.

Next, check that the source packages are in use within the system. You do this by querying the .boot.cfg.srcPaths table within any process. Any modified client files within this src folder can be picked up by a process once it is restarted.