Skip to main content
Skip table of contents

Elements

Overview

An Add-on package is composed of one or more of the Add-on Extension Mechanisms. When talking about packaging, we call these extension mechanisms elements. The element types are AddOnTool, Plugin, DataLabFunctions, and FormulaPackage. An Add-on package must have at least one element, but it is allowed to have any combination and any number of each element type. The decision about which elements to include is dependent upon the solution being developed and the preferences of the developer.

Contents

As a reminder, an Add-on package is simply a zip file (with a .addon extension) containing the elements that make up the Add-on, along with a configuration file that describes the contents of the Add-on. The structure of our example Add-on package, com.seeq.addon.example-1.0.0.addon, looks like this:

CODE 
.
├── addon.json
├── additional_content
│   └── previewImage.png
├── data-lab-functions
│   ├── API.ipynb
│   └── requirements.txt
├── frontend
│   └── com.seeq.addon.example.frontend.plugin
├── test_tool
│   ├── TestTool.ipynb
│   └── requirements.txt
└── udf
    └── formula_package.json

The following conventions are dictated:

  • There must be a JSON file named addon.json at the top level. This file contains metadata about the Add-on that is needed for installation as well as locating and interpreting the other files in the Add-on package.

  • Each element should be placed in a separate folder. You can choose folder names that make sense to you. The names you choose will be referenced in the addon.json file.

    • If AddOnTool or DataLabFunctions element types have Python requirements that need to be installed, they must be specified in a file named requirements.txt. See Best Practices for more information

    • The name of the DataLabFunctions Notebook (API.ipynb in the example) is used in the URL when calling a Data Lab Function, so it must be named with URL friendly characters.

    • Any Frontend Plugins must be in a file that ends with a .plugin file extension. Frontend Plugins are also zip files, but with a .plugin extension. They contain all the HTML/CSS/JavaScript and resources required to display the Frontend Plugin in the browser. Since the focus of this article is on packaging, we'll defer discussion of Frontend Plugin development for now and cover it in another article.

    • The FormulaPackage element type must have a single file named formula_package.json that contains the formula package specification. In our example, the UDF folder (which stands for “User Defined Functions”) contains this file.

  • Any additional content such as preview images of the Add-on can be place anywhere in the .addon file and referenced in the addon.json file. However its good practice to organize them. In this example we are keeping the preview images in folder named additional_content

Configuration

The addon.json file is what the Add-on Manager reads to get metadata about an Add-on and interpret the contents of the .addon package. This information is displayed in the "Additional Information" panel of the Add-on Manager.

The identifier, name, description, version, and license properties all contain metadata strings that are displayed in the Add-on Manager. As mentioned previously, the identifier must be unique, so reverse domain naming is recommended.

The icon property can be a Font Awesome Version 5 class name, an SVG path, or the file name of an .png file (recommended size 80x80 pixels) that is in the .addon package.

The maintainer property should contain the name of the person or company that maintains the Add-on.

The elements property specifies a list of elements supplied by the Add-on.

Common Element Properties

Every element type has the following properties:

name: Give each element a descriptive name that matches or ties in the the overall Add-on name. The name is used when the element is displayed.
identifier: Each element must have a unique identifier. It’s best practice to use the top level Add-on identifier as the root with something else unique dot-appended (e.g. .frontend) for each element.
type: The element type. One of AddOnTool, Plugin, DataLabFunctions, or FormulaPackage.
path: The name of the folder containing the element’s files.

All letters in the identifier must be lowercase.

Example:

✅ "identifier": "com.seeq.addon.example.frontend"

🚫 "identifier": "com.seeq.AddOn.Example.Frontend"

This is enough information to configure many elements. The following element properties, from the example above, provides the information needed by the Add-on Manager to install the Frontend Plugin element:

CODE 
{
  "name": "Example Plugin",
  "identifier": "com.seeq.addon.example.frontend",
  "type": "Plugin",
  "path": "frontend"
}

Here is an example of an addon.json file:

The resource_size is an optional parameter that requires the Seeq Administrator to enable the Feature/DataLab/Resource_Sizing configuration option. Not all customers will have this feature enabled, and if it is not enabled, it will result in an error during installation. Only use this option if you need to change the resource sizing.

Expand this to see the contents of the addon.json file
JSON 
{
    "identifier": "com.seeq.addon.example",
    "name": "Example Add-on",
    "description": "An example Add-on with all element types",
    "version": "1.0.0",
    "maintainer": "Seeq",
    "license": "Seeq",
    "icon": "fa fa-ghost",
    "previews":["additional_content/previewImage.png"],
    "elements": [
        {
            "name": "Example Plugin",
            "identifier": "com.seeq.addon.example.frontend",
            "type": "Plugin",
            "path": "frontend"
        },
        {
            "name": "ExampleCalc",
            "identifier": "com.seeq.addon.example.udf",
            "type": "FormulaPackage",
            "path": "udf"
        },
        {
            "name": "Example Data Lab Functions",
            "identifier": "com.seeq.addon.example.datalabfunctions",
            "type": "DataLabFunctions",
            "path": "data-lab-functions"
        },
        {
            "name": "Example Add-On Test Tool",
            "description": "A test Add-on Tool",
            "identifier": "com.seeq.addon.example.tool",
            "type": "AddOnTool",
            "path": "test_tool",
            "notebook_file_path": "TestTool.ipynb",
            "resource_size": "GP_S",
            "extensions": [],
            "configuration_schema": {
                "type": "object",
                "properties": {
                    "display": {
                        "type": "object",
                        "properties": {
                            "icon": {
                                "type": "string",
                                "default": "fa fa-wrench"
                            },
                            "linkType": {
                                "enum": [
                                    "window",
                                    "tab",
                                    "none"
                                ],
                                "default": "window"
                            },
                            "sortKey": {
                                "type": "string",
                                "default": "a"
                            },
                            "windowDetails": {
                                "type": "string",
                                "default": "toolbar=0,location=0,scrollbars=0,statusbar=0,menubar=0,resizable=0,height=550,width=420"
                            },
                            "reuseWindow": {
                                "type": "boolean",
                                "default": true
                            },
                            "includeWorkbookParameters": {
                                "type": "boolean",
                                "default": true
                            }
                        },
                        "required": [
                            "icon",
                            "linkType",
                            "sortKey",
                            "windowDetails",
                            "reuseWindow",
                            "includeWorkbookParameters"
                        ]
                    },
                    "project": {
                        "type": "object",
                        "properties": {}
                    }
                },
                "required": [
                    "display"
                ]
            },
            "configuration_filename": "configuration",
            "configuration_converter": "json"
        }
    ]
}

Element Specific Properties

Some elements have additional properties as outlined below.

AddOnTool

  • description The description provides additional context. It is displayed on the tool card just below the name of the tool.

  • notebook_file_path The name of the Jupyter Notebook containing the Add-on Tool (e.g. TestTool.ipynb) that is located in the folder specified in the element path property. The Notebook contains the user interface that will be launched when a user clicks on the Add-on Tool.

  • extensions Jupyter notebook extensions that are needed by the Add-on Tool (e.g. ["qgrid"]).

  • shared_project_identifier An AddOnTool element typically consists of a single Jupyter Project that is created by the Add-on Manager and referenced from a single Seeq Add-on Tool appearing in the Analysis Tools Panel. In cases where additional Add-on tools are needed that reference the same Project, specify the identifier of the first AddOnTool element in this property and it will reference the same Project as the other tool instead of creating a new one.

  • known_aliases Other names that this AddOnTool could have been previously installed as. Please refer to Known Aliases for more information.

The resource_size can also be configured for elements that use Seeq Data Lab as the backend, such as AddOnTool and DataLabFunctions. This is an optional field with a default of “GP_S.” The “GP_S” size is the default when a Data Lab Project is initialized. It is recommended to increase resources only if the current Add-on is failing due to resources.

Resource Sizing Options

Name

Recommended Use

UI_S

Ideal for a simple UI interface with Data Lab Functions. They are intended to be used for lightweight calls that are not resource intensive such as a simple spy.pull() or quick data manipulation.

GP_S

(Default) - This is the default resourcing and should be able to handle the majority of tasks. If your script can run in a Data Lab Project without problems then this should be used.

GP_M

Slightly more resources than the GP_S. This should be use for more complex and larger in-memory datasets.

ML_L

Should only be used for larger scripts that are rely heavily on multiprocessing or Machine Learning type operations. Such operations include execution of a machine learning model.

ML_XL

USE WITH CAUTION: This should only be used for extremely large datasets and large Machine learning tasks such as training models.

Element Configuration Schema

Some element types such as AddOnTools and DataLabFunctions may need additional configuration upon installation. These elements can specify a schema with default values, a configuration file name, and a configuration file type.

Although this makes the configuration file larger and initially appear more complex, it’s highly flexible and easily understandable after a brief explanation. It allows the Add-on Manager to validate user-supplied configuration settings to ensure each element gets the configuration it needs and to provide useful error messages when there is a problem.

The configuration_schema property from the addon.json file has been separated out and displayed below to aid discussion. In actual use, an element’s configuration_schema is specified as a property of the element in the addon.json file.

Expand to see the example configuration_schema for an AddOnTool element
JSON 
"configuration_schema": {
    "type": "object",
    "properties": {
        "display": {
            "type": "object",
            "properties": {
                "icon": {
                    "type": "string",
                    "default": "fa fa-wrench"
                },
                "linkType": {
                    "enum": [
                        "window",
                        "tab",
                        "none"
                    ],
                    "default": "window"
                },
                "sortKey": {
                    "type": "string",
                    "default": "a"
                },
                "windowDetails": {
                    "type": "string",
                    "default": "toolbar=0,location=0,scrollbars=0,statusbar=0,menubar=0,resizable=0,height=550,width=420"
                },
                "reuseWindow": {
                    "type": "boolean",
                    "default": true
                },
                "includeWorkbookParameters": {
                    "type": "boolean",
                    "default": true
                }
            },
            "required": [
                "icon",
                "linkType",
                "sortKey",
                "windowDetails",
                "reuseWindow",
                "includeWorkbookParameters"
            ]
        },
        "project": {
            "type": "object",
            "properties": {}
        }
    },
    "required": [
        "display"
    ]
},
"configuration_filename": "configuration",
"configuration_converter": "json"

At each level of the configuration schema, you’ll see the type, properties, and required properties. These properties can be used to define whatever configuration schema is needed by the Add-on element.

  • type specifies the type of the property. In the example above we see examples of object, string, boolean. The enum property defines the enumeration without the need for a type property.

  • default The default value for the property. This value will be used if a configuration file is not supplied with the Add-on. The Admin will have the option to change the default value when installing the Add-on.

  • required Contains an array of property names that are required to be in the configuration for validation to succeed. When an Add-on is first installed, the default configuration generated from the schema will only include required properties.

The specific properties seen above in the display property (e.g. icon, linkType, sortKey, etc.) are used to configure how the AddOnTool element displays the Add-on Tool when it is opened.

Please note that the icons specified in the configuration_schema for Add-on Tools are compatible with Font Awesome 4.7. However, icons used within the Add-on itself utilize Font Awesome 5.

In the example above, the project configuration property doesn’t contain anything. This section could be used by an AddOnTool or DataLabFunctions element to supply configuration settings to the Data Lab Project.

The configuration_filename property defines the name of the file that is used to store the configuration in the Project. Configuring this name can be useful if the project code expects a particular file name.

Additionally, a configuration_converter format can be specified. Values of json, toml, and ini are allowed. This specifies the file format of the configuration that is persisted to the Project. Although the Add-on Manager user interface always presents the configuration as JSON, it can be useful to persist the configuration file in a different format if the configuration is primarily used by an Add-on dependency that expects a different format.

The Add-on Manager presents the specified configuration to the Administrator and allows it to be modified.

Add-on Manager Configuration Modal

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close