Getting started

This plugin is currently in alpha state. It is not recommended to rely on this plugin in production.
This plugin requires an instance with InvenTree 0.13.0 or higher and plugin support.

Enables "sharing" of certain stock items between multiple InvenTree instances. There are some known limitations in the current implementation.

General information about InvenHost

The InvenHost project aims to provide a set of plugins and service that enhance InvenTree for commercial and enterprise use cases.

Read more about InvenHost in the main project documentation

Installation/setup

  1. Install the plugin. To do this either:

    1. Install the plugin directly from the InvenTree UI. Go to Settings → Plugins and click on Install plugin. Enter the URL of this repository and click on Install.

    2. Install the plugin in your environment with pip. Run

pip install --index-url https://git.invenhost.com/api/packages/invenhost-c1/pypi/simple/ inventree-federation

  1. Then active the new federation entry in the plugin table in the InvenTree UI.

  2. Go to the plugin settings for inventree-federation and activate the settings discoverable by other instances.

Function

TODO

Use cases

These use cases guided the development of this plugin. New additions to the plugin should not conflict with these use cases. If they do the reason needs to be documented.

In the following Party A is the InvenTree instance of the makerspace of the main user. Party B is the InvenTree instance of the makerspace of the user’s friend/friendly hack. All descriptions are from the perspective of the main user. The parties trust each other. Party C is another makerspace that is not trusted by/known to the main user. Party x means any trusted party.

UC 1: Federation setup

Every server can request to connect to every server (with in the default throtteling) and can be connected to by every server. A superuser of the reqeuseted server needs to be allow the connection. If that occurs a user account for the requesting server is created and a long lived token (1 year) is created. Additionally a customer is created for the requesting party. This will server as the owner of the stock items that are shared with the requesting party.

Diagram

UC 2: Party A sends item to party B

One Party pushes a stockitem to antother. The receiving Party needs to accept the item. It will then be created on the receiving Parties Instance and moved on the sending Parties instance to the customer account of the receiving parties customer account.

Diagram

UC 3: Party B request item from party A

Similar to UC2 but the other way around. The sending Party needs to accept the item.

Diagram

UC 4: Party x requests inventory stats from party x

Diagram

UC 5: Federation stop

TODO

Design decisions

  1. The plugin should follow InvenHost best practices

  2. The plugin should not use migrations

  3. The plugin should expose a reusable REST API

  4. The user interface is to be implemented in CUI till PUI is GA

  5. Data is to be stored in metadata

  6. Changes to stock etc. are to be tracked in the history

  7. Each Federated party is to have it’s own customer

Known Limitations

UC 6: Party A sends to party B sends to party C

Not allowed. Only direct connections are allowed currently as the plugin does not keep track of the full chain of ownership.

Multi step/dynamic approval process

This is out of scope currently. Might be possible once the inventree-approvals plugins is GA.

The auth tokens need to be updated yearly

The default for 0.13.0 is that the auth tokens are valid for 1 year. This means that the auth tokens for all connections need to be updated yearly. This is an acceptable tradeoff for the current implementation.

Background

This plugin is mainly developed to address the ask for federation in upstream InvenTree. The idea is that multiple makerspaces would like to be able to share selected tools and inventory states between each other. This plugin is a first step towards that goal. The use cases were worked on at 37c3.