Skip to content

Overview

InvenTree Plugin Architecture

The InvenTree server code supports an extensible plugin architecture, allowing custom plugins to be integrated directly into the database server. This allows development of complex behaviours which are decoupled from core InvenTree code.

Plugins can be added from multiple sources:

  • Plugins can be installed in InvenTrees venv via PIP (python package manager)
  • Custom plugins should be placed in the directory ./InvenTree/plugins.
  • InvenTree built-in plugins are located in the directory ./InvenTree/plugin/builtin.

For further information, read more about installing plugins.

Plugin Base Class

Custom plugins must inherit from the InvenTreePlugin class. Any plugins installed via the methods outlined above will be "discovered" when the InvenTree server launches.

Namechange

The name of the base class was changed with 0.7.0 from IntegrationPluginBase to InvenTreePlugin. While the old name is still available till 0.8.0 we strongly suggest upgrading your plugins. Deprecation warnings are raised if the old name is used.

Imports

As the code base is evolving import paths might change. Therefore we provide stable import targets for important python APIs. Please read all release notes and watch out for warnings - we generally provide backports for depreciated interfaces for at least one minor release.

Plugins

General classes and mechanisms are provided under the plugin namespaces. These include:

# Management objects
registry                    # Object that manages all plugin states and integrations

# Base classes
InvenTreePlugin             # Base class for all plugins

# Errors
MixinImplementationError    # Is raised if a mixin is implemented wrong (default not overwritten for example)
MixinNotImplementedError    # Is raised if a mixin was not implemented (core mechanisms are missing from the plugin)

Mixins

Mixins are split up internally to keep the source tree clean and enable better testing separation. All public APIs that should be used are exposed under plugin.mixins. These include all built-in mixins and notification methods. An up-to-date reference can be found in the source code (current master can be found here).

Models and other internal InvenTree APIs

Danger Zone

The APIs outside of the plugin namespace are not structured for public usage and require a more in-depth knowledge of the Django framework. Please ask in GitHub discussions of the ÌnvenTree org if you are not sure you are using something the intended way.

We do not provide stable interfaces to models or any other internal python APIs. If you need to integrate into these parts please make yourself familiar with the codebase. We follow general Django patterns and only stray from them in limited, special cases. If you need to react to state changes please use the EventMixin.

Plugin Options

Some metadata options can be defined as constants in the plugins class.

NAME = '' # Used as a general reference to the plugin
SLUG = None  # Used in URLs, setting-names etc. when a unique slug as a reference is needed -> the plugin name is used if not set
TITLE = None  # A nice human friendly name for the plugin -> used in titles, as plugin name etc.

AUTHOR = None  # Author of the plugin, git commit information is used if not present
PUBLISH_DATE = None  # Publishing date of the plugin, git commit information is used if not present
WEBSITE = None  # Website for the plugin, developer etc. -> is shown in plugin overview if set

VERSION = None  # Version of the plugin
MIN_VERSION = None  # Lowest InvenTree version number that is supported by the plugin
MAX_VERSION = None  # Highest InvenTree version number that is supported by the plugin

Refer to the sample plugins for further examples.

Plugin Config

A PluginConfig database entry will be created for each plugin "discovered" when the server launches. This configuration entry is used to determine if a particular plugin is enabled.

The configuration entries must be enabled via the InvenTree admin interface.

Disabled by Default

Newly discovered plugins are disabled by default, and must be manually enabled (in the admin interface) by a user with staff privileges.

Plugin Mixins

Common use cases are covered by pre-supplied modules in the form of mixins (similar to how Django does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.

Supported mixin classes are:

Mixin Description
ActionMixin Run custom actions
APICallMixin Perform calls to external APIs
AppMixin Integrate additional database tables
BarcodeMixin Support custom barcode actions
CurrencyExchangeMixin Custom interfaces for currency exchange rates
EventMixin Respond to events
LabelPrintingMixin Custom label printing support
LocateMixin Locate and identify stock items
NavigationMixin Add custom pages to the web interface
PanelMixin Add custom panels to web views
ReportMixin Add custom context data to reports
ScheduleMixin Schedule periodic tasks
SettingsMixin Integrate user configurable settings
UrlsMixin Respond to custom URL endpoints
ValidationMixin Provide custom validation of database models