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 via PIP (python package manager)
- Custom plugins should be placed in the directory
- InvenTree built-in plugins are located in the directory
Note: Plugins are discovered and loaded only when the server is started.
Enable Plugin Support
To enable custom plugins, plugin support must be activated in the server configuration.
Have you tried turning it off and on again?
When new plugins are installed (and activated), both the web server and background worker must be restarted.
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.
The name of the base class was changed with
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.
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.
Generall classes an 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 are split up internally to keep the source tree clean and enable better testing seperation. 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¶
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.
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 VERSION = None # Version of the plugin WEBSITE = None # Website for the plugin, developer etc. -> is shown in plugin overview if set
Refer to the sample plugins for further examples.
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.
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: