Creating the Plugins - Kaholo

Creating the Plugins

1. Plugins

Kaholo plugins wrap around the products/resources a user may want to use within Kaholo for pipeline executions.

Each plugin allows you to utilize its methods (and its own parameters) locally and can be executed along the automation process.

Plugins are written in JavaScript and are executed using Node.js.

In order to use a plugin, simply drag and drop the desired plugin into the Kaholo Designer and connect it with other processes in the pipeline.

In the following sections, we’ll describe how you can develop your own custom plugins for Kaholo. 

2. Plugin Structure

The default structure for any plugin is:

  1. config.json – The file containing all of the plugin’s configurations. This includes the settings fields, methods along with their parameters, and all of the metadata for the plugin like its name and description.
  2. package.json – The file containing all data about the npm packages (external packages) that are used in the plugin’s code.
  3. app.js – The file containing the code for all of the plugin’s external methods that are shown in the Kaholo UI, and declared in the config.json file. Doesn’t have to be named “app.js” but has to end with “.js”.
  4. logo.png – An image file containing the logo that will be shown to users for the plugin. Doesn’t have to be named “logo.png” but it’s recommended to use a PNG file.
  5. helpers.js (Optional) – A file containing all helper functions used in app.js, such as authentication methods or creating a client for communicating with an API.
  6. autocomplete.js (Optional) – A file containing all auto-complete functions and helper methods, in case any auto-complete parameters were declared in the config.json file.
  7. parsers.js (Optional) – A file containing parsing functions for all of the parameter types.

2.1. config.json

Fields:

  • name – The name of the plugin. Must only contain alphanumeric characters, hyphens, and underscores.
  • type – Can be either “executer” for plugins, or “trigger” for triggers. For now we will stick to plugins, and so we will use “executer”
  • imgUrl – The local path relative to the config file of the logo file.
  • execProgram – currently only supports “node” for node.js.
  • main – The local path relative to the config file, of a JavaScript code file which exports all the methods declared in the “methods” parameter.
  • version – The current version of the plugin. In the format of <num>.<num>.<num>, for example, “1.0.0”.
  • description – A short description of the plugin.
  • Settings – An array of all the settings of the plugin. The setting object format is the same format that is used for plugins and you can find more info about it in section 3 below.
  • methods – an array of method objects for all of the plugin’s methods. Each Method object needs to contain the following fields:
    • name – The name of the method exported from the code
    • viewName – The name of the method shown to users in the Kaholo UI
    • params – The parameters of the method. You can find more info on parameters in section 3 below.

2.2. package.json example

The package.json file contains all data on the plugin as an npm package. This is required for using any external npm packages, such as “node-fetch” used in this example.

You can read more about the package.json file here.

 

3. Method parameters and plugin settings

Both method parameters and plugin settings are provided in the same format in the config.json file. The basic format for either parameters or settings is:

Each parameter object is required to have the following fields:

  • name – The name in the code of the parameter or setting.
  • viewName – The name shown in the Kaholo UI for this parameter or setting.
  • Type – The type of the parameter or setting. Possible types are: string | text (multi-line string) | boolean | vault | options | autocomplete (only for method parameters).

For options and auto-complete parameters, more fields are required which will be described in sections 3.1 and 3.2 below.

It is recommended to parse the parameters and settings in the code to the format of values used in the code or in any external packages.

It is also important to note that method parameters can be passed from the pipeline’s code layer, and so can also accept any type of data supported by JavaScript.

3.1. Options parameters and settings

The Options type Parameters and Settings are presented in the Kaholo UI as a drop-down button where the user is prompted with a list to select the desired option.

The Options type Parameters and Settings should include an additional field called “options”, like this:

The value of the “options” field should be an array of objects with two fields:

  • id – The value passed to the parameter or setting in the code. It must be a string.
  • name – The text shown in the Kaholo UI for this option. It must be a string.

3.2. Auto-complete parameters

Currently only method parameters support the autocomplete type. Autocomplete parameters are presented to the user in a similar format to the options type. The user is prompted with a drop-down menu connected to a text box where the user enters the query. Autocomplete parameters can be useful for many different use cases, from showing a queried list from an API of possible resources, to prompting the user to enter a date in a specific format.

Autocomplete parameters require a few additional fields in the config.json file:

Currently the only supported value for the “autocompleteType” field is “function”. The field “functionName” should contain the exported name of the autocomplete function in the app.js file (If it’s declared in the autocomplete.js file make sure to include and export it from app.js as well).

Autocomplete parameters store their value in the format of an object with two fields:

  • id – A unique identifier not shown to the user but accessible from the plugin code.
  • value – The text shown to the user in the Kaholo UI for this autocomplete option in the drop-down menu. This is also accessible from the plugin code.

You can see an example of how to write an autocomplete function in section 5.

4. Plugin Code

All plugin’s code should be written in JavaScript. You should export all of your external methods from the file specified as “main” in the config.json file.

The Kaholo Server expects all external methods that can be used by Kaholo users to be async.

Each method declared in the config.json file needs to be in the following format:

Both action and settings are always sent as an input, and are objects containing all metadata and params of the action, and all of the plugin’s settings. You can reach each parameter or setting using action.params.paramName \ settings.settingName .

You can see some example code for plugins in the following links:

5. Auto-complete Functions

When using the autocomplete parameter type, you need to provide it with a function from the code that knows how to handle that parameter.

Autocomplete functions need to be exported from the main code file as well, but it’s better to implement them in a different file, usually named autocomplete.js. All autocomplete functions are expected to be in the following format:

Which means, it expects an async function, which receives 3 inputs: query (the current text entered by the user in the param’s text box), plugin settings, and action parameters. Both plugin settings and action parameters are received in the format of an array of objects containing key and value. In order to access params the same way used in other Kaholo methods, you need to first parse the params and settings to objects instead of arrays.

You can do so using the following method:

You can see some examples of autocomplete functions, here:

  • LogicMonitor plugin autocomplete file: https://github.com/Kaholo/kaholo-pluginlogicmonitor/blob/main/src/autocomplete.js
  • Okta plugin autocomplete file: https://github.com/Kaholo/kaholo-plugin-okta/blob/main/src/autocomplete.js

Close Menu