Currently only Python 3.7 code is supported, so this will be the first thing to get installed on your local workstation. Then download this requirements.txt file so you have the correct libraries and their version available. Install using
pip install -r requirements.txt.
A plugin receives an input manifest as first command line argument, and the output file path via the second arguments. A report plugin run would look like this:
A basic python plugin would look like this:
It's important to note that the output JSON should always be written to
argv; in production this location will be writeable. In general, any files during your plugin run should written to the current path, thus no absolute or other paths, because they will not exist or not be writeable when your plugin runs on the platform in production.
First we read the JSON manifest file. Then we construct a basic JSON plugin results object, shown in the
output variable in the example above.
data key can contain anything you like and will be available as-in in the context of the
js context and then
jsx to display the visualizations — each of which can call any optionally defined
js— here we have access to a global
resultsvariable; an object containing the plugin results. This
resultsobject contains two properties:
datawhich is whatever
datawas returned from Python in the output JSON and
helpersis a helper class that can be optionally outputted in the output JSON.
The object returned in
jswill be available in the
jsxcontext as the
datavariable. Normally the
jsproperty will not be used; instead it's best to use the
helperinstead because that will allows for better re-use of any helper code. If used, it's important that the JS code has code at the end of the file, and not comments. See the third item below.
jsx— here we render any JSX components/tags to visualize our plugin. For a full overview of JSX components and API functions see the see the API library. Here we have access to the same global
resultsvariable. In addition we also have access to a variable called
data, which contains whatever was returned from the
jscode. In most cases
jsshould not be used, and there is thus no returned
dataavailable. Instead we use the
helperclass instead, as this will allow for easier code re-use, especially when this plugin is available to third-parties.
helper— this is the main glue of the plugin, and defines functions that can be re-used in the
jscode parts. Within the helper code, you can access
thisto call another helper function. All helpers are also pre-initialized with
this.results, which gives you access to the plugin
resultsobject. The helper functions can also be documented with a JSON format, making them available to third-parties where they can be re-used in the Insight API, with fully ready to use code examples. See the Plugin Helpers documentation for more details.
Finally a plugin ouput should always contain a valid
status object. In case of no errors, it can simply look like this:
In case of an error, it's most basic format would be:
You can also provide a friendly title for end-users in the
title key, together with a more detailed error message for the end-user in
explanation. Any backtrace can be put into the
backtrace. All fields are optional, so you can supply whatever you have available. A full error would look like this:
While the plugin code above thus shows how to use the full
helper formats, normally you would only use the
helper parts. The code would then be structure more like this:
Helper functions should not really be used to do intensive work, which is done instead in the plugin itself. The helpers should be a glue layer that render components, visualizes
data — by mapping this custom object to the format for different visualization components, and to expose convenience functions for users of the plugin, which could be yourself or third-parties in case you publish the template.
helper there is access to a range of visualization components, utility methods and libraries to make developing plugins as easy as possible. See the API library for more details.