The plug-in manifest

Every i2 Notebook plug-in requires a manifest, which is a JSON file that provides configuration settings for the plug-in. The file must appear at the root of the plug-in directory, and it must be named plugin.json.

Most of the settings that the manifest can provide are mandatory. The file must contain the following information:

• A unique identifier for the i2 Notebook plug-in
• The version of the plug-in
• A name for the plug-in, to appear in diagnostic messages for plug-in lifecycle events
• The path to the entry point JavaScript file to load, relative to the manifest

Optionally, the manifest can also specify changes to i2 Notebook's content security policy, so that the plug-in can access content on servers that the policy would otherwise block.

Creating a manifest

The i2 Notebook SDK includes a JSON schema that enforces the structure and content of plug-in manifests. The Liberty server validates your manifests when it reads them, but you can also use the schema to assist during manifest creation from a compatible editor (such as Microsoft Visual Studio Code).

The file name of the schema is plugin-manifest.json. To reference it from your plugin.json file, include the $schema field as the first entry in the manifest, like this:

{
    "$schema": "https://i2group.github.io/notebook-sdk/schemas/plugin-manifest.json",
    ...
}

After you set this field, editors that support JSON schemas provide inline help to ensure that mandatory fields in the manifest are present and populated with valid values.

Plug-in manifest syntax

The following fields are valid in an i2 Notebook plug-in manifest:

Name	Mandatory?	Description
entryPointCsp	No	Directives to add to the HTTP Content-Security-Policy response header for the entry point JavaScript file.
entryPointUrl	Yes	The URL of the entry point JavaScript file, relative to the manifest file.
name	Yes	The name of the plug-in, which might appear in status messages.
pluginId	Yes	The identifier of the plug-in, as a lower-case GUID.
pluginVersion	Yes	The version of the plug-in, typically in x[.y[.z]] format.
toolViewCsp	No	Directives to add to the HTTP Content-Security-Policy response header for tool view files.

For example:

{
    "$schema": "https://i2group.github.io/notebook-sdk/schemas/plugin-manifest.json",
    "pluginId": "01234567-89ab-cdef-0123-456789abcdef",
    "pluginVersion": "1.0",
    "name": "My i2 Notebook plug-in",
    "entryPointUrl": "./entrypoint.js",
    "toolViewCsp": {
        ...
    }
}

Content security policy directives

By default, i2 Notebook's content security policy (CSP) prevents plug-ins from accessing some kinds of information on servers that are not the i2 Analyze server. However, and especially if your plug-in uses tool views, you might need to use code, fonts, or other data that are located on another server. In such cases, you can use the toolViewCsp field to allow access to that server from tool views.

In rarer cases (but for the same reasons), you might need to change the CSP that applies to the entry point JavaScript file. For example, if you want to connect to a remote service on the execution of a command, you can use the entryPointCsp field to allow access to the service for that purpose.

For more information about CSP directives and how to choose which ones you need, see the documentation at MDN Web Docs. In the manifest, you populate entryPointCsp and toolViewCsp with fields whose names match CSP directive names, and whose values are the URLs of servers that your plug-in will access, or are drawn from a small group of keywords:

{
    ...
    "entryPointCsp": {
        "connect-src": "http://external-server-to-access-from-entry-point",
    },
    "toolViewCsp": {
        "connect-src": "http://external-server-to-access-from-tool-view",
        "img-src": "http://external-server-that-provides-images"
    }
}

Note: To specify more than one value in a "connect-src" or "img-src" field, you can add space-separated values between the double-quote characters.

For example: "http://external.com http://example.com"

The set of available CSP directives can and does change over time. Especially if your plug-ins make regular use of CSP directives, ensure that you stay abreast of updates to the MDN documentation.