Enterprise Features

Some features of Sakuli require an enterprise license. Please consult our overview to see and request packages and prices. After you registered for an enterprise subscription, you will get a license-key and an NPM access token which are required to use enterprise features.

Assisted Setup

It is assumed that you have setup your environment as described in the Getting Started Guide.

On the commandline, navigate to the root folder of your Sakuli project (where the package.json file is located) and run the following command:

npx sakuli enable-enterprise

This command starts an assistant which will guide you through the setup of enterprise features. The first question is regarding the Sakuli-license key which you should have received after subscribing to an enterprise package.

? Would you like to enter your Sakuli license information? (Y/n)

You can enter n when you have already entered the license information before.

You can enter Y and paste the license key in the next prompt:

? Please enter your license key:

Same applies to the NPM access token which can be pasted / entered in the next prompt:

? Please enter your npm key:

The following prompt asks you about the enterprise features which you want to activate. You can use and to navigate the cursor and SPACE to select or deselect a feature. Pressing ENTER will submit your selection and start the setup process.

? Please Select Enterprise Features to bootstrap (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◯ Forwarding to Icinga2
 ◯ Forwarding to checkmk
 ◯ Forwarding to OMD

Sakuli will then configure the license information globally and add install and preconfigure the selected enterprise features in your project.

You can now just start using your feature:

The next sections is about how to setup enterprise features manually and in more detail.

Manual Setup

With your active Sakuli Enterprise subscription you will receive an email with:

  • Sakuli license-key - Contains information about your subscription and is used by Sakuli itself
  • and a NPM-Token - Allows access to Sakuli’s private enterprise packages on NPM

There are several ways to handle these information. The most simple way for setting up your enterprise features is as follows (substitute the placeholders between the chevrons with the appropriate values):

Global configuration

The most simple way to get your enterprise features to work is the following configuration (substitute the placeholders marked by the angle-brackets with its appropriate values):

On Unix / OSX

echo "//registry.npmjs.org/:_authToken=<Put your personal NPM-TOKEN here>" > ~/.npmrc
echo "export SAKULI_LICENSE_KEY=<Put your personal SAKULI-LICENSE-KEY here>" >> ~/.bashrc

On Windows

echo //registry.npmjs.org/:_authToken=<Put your personal NPM-TOKEN here> > %USERPROFILE%\.npmrc
setx SAKULI_LICENSE_KEY=<Put your personal SAKULI-LICENSE-KEY here>

The environment variables might not take effect in the command-line window where the commands above are entered. So you might need to open a new commandline when running the Sakuli command.

These commands will set the NPM-Token and License Key globally. This is good for a first setup on your machine but might have some shortcomings in more advanced situations. The following paragraphs describe alternative ways to provide NPM-Token and License information to your Sakuli installation.

Now you are ready to go for using Sakuli with its enterprise features like

Per-Project configuration of NPM-Token

You can set the NPM-Token for each project by adding a .npmrc file to your project’s root directory:

On Unix / OSX

# cd path/to/project
echo "//registry.npmjs.org/:_authToken=<Put your personal NPM-TOKEN here>" > .npmrc

On Windows

# cd path/to/project
echo //registry.npmjs.org/:_authToken=<Put your personal NPM-TOKEN here> > .npmrc

This command will create an .npmrc file with the necessary token configuration inside your specific project folder. Every upcoming npm install will use this configuration.

Per-Project configuration with environment variable

If you don’t like to save the token in a file (because this file might be shared) you can configure it to use an environment variable:

On Unix / OSX

echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" > ~/.npmrc

On Windows

echo //registry.npmjs.org/:_authToken=${NPM_TOKEN} > %USERPROFILE%\.npmrc

On Unix / OSX

NPM_TOKEN=<Put your personal NPM-TOKEN here> npm i <ENTERPRISE-PACKAGE>

On Windows

set NPM_TOKEN=<Put your personal NPM-TOKEN here>
npm i <ENTERPRISE-PACKAGE>

This approach is frequently used in automation scenarios such as CI/CD pipelines and projects that are shared (e.g. via version control systems).

It is usually not necessary to persist the token since you will seldomly run npm install that often.

Using the License-Key

The license-key contains information about your subscription which will be checked by enterprise components before they are executed. In order to provide this License-Key to Sakuli you also have to set it as an environment variable. Because the license-key is read on every single test execution it is useful to store it persistently on your system or set it in a script where the actual test is also called.

The name of the environment variable for the license-key is SAKULI_LICENSE_KEY.

More about Environment Variables

An environment variable is a dynamic-named value that can affect the way running processes will behave on a computer. They are part of the environment in which a process runs. For example, a running process can query the value of the TEMP environment variable to discover a suitable location to store temporary files, or the HOME or USERPROFILE variable to find the directory structure owned by the user running the process.

- Wikipedia, 08/2019

So basically an environment variable is just a simple key-value pair provided to a certain process e.g. VAR_NAME=VALUE. They can be set for each process or system-wide - so that they become accessible for each upcoming process.

The approach for integrating an environment variable depends on the respective operating system.

On Windows

To set up an environment variable on Windows you have to:

  • Open Start-Menu and type env into the search mask
    • An entry ‘Edit the system environment variables’ should appear (click on it)
  • After the System Properties dialog showed up
    • Go to the Advanced tab
    • Click on the button Environment Variables (at the bottom of the dialog)
  • You should see two tables including Variable and Value columns for User Variables and System variables

There you can set, edit or delete environment variables permanently on your system (it is recommended to edit the system variables table if possible). A more detailed guide can be found here.

Alternatively you can use Rapid Environment Editor which is a nice tool for editing environment variables on Windows.

In case of a more restrictive environment - where it is not possible to edit environment variables that easily - you can set them in a batch script:

run-sakuli.bat

SET SAKULI_LICENSE_KEY=<PERSONAL_LICENSE>
sakuli run .

On Linux or OSX

On Linux or OSX it is usually a file which sets up the environment for certain processes:

  • ~/.bashrc on Linux
  • ~/.profile on OSX

These files can be changed with every text editor to add, edit or remove environment variables. An environment variable is defined by:

export VARIABLE_NAME=VALUE

A new variable can be added with the command:

echo "export VARIABLE_NAME=VALUE" >> ~/.bashrc  # Linux
echo "export VARIABLE_NAME=VALUE" >> ~/.profile # OSX