Plugins

This section explains how plugins can be installed and configured to extend the functionality of Kadi4Mat. It is recommended to have a working Kadi4Mat installation before reading through this section. For general information about configuring Kadi4Mat, please also see Configuration.

Installing plugins

Plugins can either be part of the main application package or implemented as independent Python packages, which have to be installed separately in the same virtual environment that Kadi4Mat itself was installed in. In both cases, plugins are configured via the PLUGINS configuration value of Kadi4Mat:

PLUGINS = ["example", "another-example"]

This will activate the plugins with the names example and another-example in the application.

Some plugins might require additional configuration to work correctly or to change how they behave. This configuration is plugin-specific and can be specified via the PLUGIN_CONFIG configuration value of Kadi4Mat. Note that the configuration always needs to be a dictionary, e.g. like in the following configuration for the example plugin:

PLUGIN_CONFIG = {
    "example": {
        "example_key": "example_value",
    },
}

First-party plugins

Currently, all first-party plugins are part of the main application package and are therefore available automatically after installing Kadi4Mat. The following sections describe each plugin in more detail.

Zenodo

The zenodo plugin allows users to connect their Kadi4Mat account to a Zenodo account in order to upload records and collections directly to the Zenodo repository.

A minimal plugin configuration may look like the following:

PLUGIN_CONFIG = {
    "zenodo": {
        "client_id": "<zenodo_client_id>",
        "client_secret": "<zenodo_client_secret>",
    }
}

The following configuration values are supported by this plugin:

client_id

The client ID required to perform the OAuth2 authorization flow with Zenodo. It can be obtained (together with the client secret) directly via Zenodo by navigating to Applications > Developer applications in the account settings page and creating a new application. Besides setting some general application metadata that will be displayed to users of the particular instance of Kadi4Mat, the following settings are necessary for the integration to work correctly:

  • Redirect URIs: https://<server_name>/settings/services/authorize/zenodo

  • Client type: Confidential

The <server_name> of the redirect URL corresponds to the configured SERVER_NAME of Kadi4Mat.

Defaults to None.

client_secret

The client secret required to perform the OAuth2 authorization flow with Zenodo. See the client_id configuration option on information on how to obtain it.

Defaults to None.

base_url

The URL of the Zenodo instance to use. For testing purposes, the Zenodo sandbox can be used instead by configuring "https://sandbox.zenodo.org".

Defaults to "https://zenodo.org".

S3

The s3 plugin provides file storage using an S3-compatible object store such as MinIO or Amazon S3. The corresponding s3 storage provider can be configured via STORAGE_PROVIDER. For general information about using different storage providers in Kadi4Mat, please refer to the storage configuration.

A minimal plugin configuration may look like the following:

PLUGIN_CONFIG = {
    "s3": {
        "endpoint_url": "https://s3.example.com",
        "bucket_name": "kadi",
        "access_key": "<s3_access_key>",
        "secret_key": "<s3_secret_key>",
    },
}

The following configuration values are supported by this plugin:

endpoint_url

The base URL of the object store.

Defaults to None.

bucket_name

The name of a bucket the storage provider operates in, e.g. "kadi".

Defaults to None.

access_key

The access key used for authentication. It is recommended to restrict access to the bucket as configured via bucket_name. If not provided, the standard configuration locations of the Boto3 client library will be checked for this value instead.

Defaults to None.

secret_key

The secret key used for authentication. If not provided, the standard configuration locations of the Boto3 client library will be checked for this value instead.

Defaults to None.

region_name

The region name to use when accessing the object store. Only relevant for certain object store implementations.

Defaults to None.

signature_version

The signature version to use for signing requests. Only relevant for certain object store implementations.

Defaults to None.

use_presigned_urls

Whether to generate presigned URLs when downloading files. This allows direct file downloads via the underlying object store, including support for range requests, but requires the object store to be reachable externally.

Defaults to True.

presigned_url_expiration

The expiration time in seconds to use for all generated, presigned URLs if use_presigned_urls is True.

Defaults to 60.

TIB TS

The tib_ts plugin provides a search for term IRIs using the TIB Terminology Service in all places where term IRIs can be specified.

The following configuration values are supported by this plugin:

endpoint

The term search API endpoint provided by the service.

Defaults to "https://service.tib.eu/ts4tib/api/search".

InfluxDB

The influxdb plugin provides a proxy connection to one or more InfluxDB instances. Once set up, users will be able to configure their connection to a specific InfluxDB instance by providing a corresponding API token in their user preferences, which is stored encrypted in the database of Kadi4Mat. Afterwards, the InfluxDB instance can be queried using the proxy endpoint /api/influxdb/<name>/query?orgID=<orgID> of Kadi4Mat, with the <name> replaced by the corresponding name of the configured InfluxDB instance and the <orgID> replaced by an organization ID within InfluxDB.

A minimal plugin configuration may look like the following:

PLUGIN_CONFIG = {
    "influxdb": {
        "<name>": {
            "url": "https://influxdb.example.com",
        }
    }
}

In contrast to other plugins, each InfluxDB instance has its own configuration and is itself specified via a unique name, mapping to the instance-specific configuration as dictionary.

The following configuration values are supported by each instance:

url

The base URL (i.e. without /api/...) of the InfluxDB instance to use.

Defaults to None.

title

The title which will be displayed to users when configuring the InfluxDB instance via the GUI of Kadi4Mat.

Defaults to the name of the corresponding InfluxDB instance.

timeout

The maximum amount of seconds a proxied request to the InfluxDB instance can last before it is aborted.

Defaults to 10.

token

A global token to use for all proxied requests to the InfluxDB instance. Takes precendence over user tokens that have been configured previously.

Defaults to None.

Warning

Be mindful about the scopes and buckets that are accessible with the provided global token.

groups

A single group ID or a list of group IDs within Kadi4Mat to restrict proxied access to the InfluxDB instance to. It is highly recommended to only specify trusted groups which are manageable by the sysadmin. Can be useful in combination with a global token.

Defaults to None.