Plugin Configuration documentation

[bdmartens]

I am new to Inventree, trying to sort my way through getting everything up and running.
It appears the plugin configuration documentation is scant, or at least incongruent with my install (Docker, 0.17.13)
I'm trying to get the Digikey barcode plugin (?renamed to just "DigiKey Plugin") configured.
The stable docs don't mention the plugin at all.
The latest does:
https://docs.inventree.org/en/latest/plugins/builtin/digikey/
It took a while to see that the word 'supplier' was a link.
It is then implied that in order to scan barcodes, you need to create a supplier, then select it.

I then do this, create a supplier (website, phone number, email, etc - no API info), go back to plugin settings for the digikey plugin, set the supplier to digikey. No futher fields are opened up to put in the ClientID or Client Secret.

Looking at other documentation for the inventory plugin, there apparently are configuration parameters for these.

I don't see forums elsewhere where this process has been answered already. I don't see any youtube videos on this, and generic google searches don't seem to turn up relevant information. As populating inventory with parts is a (presumably) common task, it would be nice if these docs could get fleshed out a bit more. I'm not sure how new this version of the plugins may be.

Is it possible to get the digikey (& mouser, etc) plugin process fleshed out a bit more, including this hangup on how to activate the plugin to get barcode features working?

Once I get things working, being fresh with the install experience, I'm happy to suggest specific content for the docs, should that be helpful (and correct)

(Separately, for those who like to create youtube content, this could be a useful area to address. There are overviews, and KiCad detailed videos, but nothing going through a basic setup, creating categories, suppliers, enabling barcode scanning, and adding parts)

[SchrodingersGat]

Looking at other documentation for the inventory plugin, there apparently are configuration parameters for these.

Please provide links here. None of our builtin plugins support API calls to a supplier.

[matmair]

I have transferred this as it has nothing to do with the website. @bdmartens please answer the question, the issue will auto close in about 3 months without answer

[bdmartens]

@matmair The connection to the website is the documentation. I was offering, once I understood the issues more, to help flesh out the documentation from a new user's perspective. I recognize that once someone knows what they are doing or has learned the required details, these may be non-issues, however I'm at the new-user stage, and was hoping to provide feedback in a way that was useful for improving documentation for those readers. The goal is to add this perspective, not to criticise and expect others to fix it. All my walls of text below are to help flesh out the content.

I think @SchrodingersGat 's clarification is quite helpful. The built-in plugins do not call APIs to the suppliers - and (my guess as to the extension) thus do not allow you to pre-populate new items with information from the suppliers. The built-in barcode scanning plugins are (I now believe) purely so that Inventree is able to extract the code from the barcode.
The builtin plugin settings page does suggest that configuration is needed. /platform/settings/admin/plugin/digikeyplugin/
This page would be nice to have descriptive text to state that the supplier needs to be created first, and then selected from a list. Without suppliers created, clicking on the config parameter doesn't give any options and seems to be a free text. Additionally, it seems odd for a builtin plugin that doesn't do API calls to need the web address for the supplier.... Not too sure what the functionality is for this plugin to need a supplier set if it doesn't search or order.

From a new user's perspective, it would be nice to see this in black & white both on the website, as well as in the plugin description in the application.

The second step is how to automate filling in parts information (my goal), and this seems to depend on a variety of different user-supplied plugins, which do require APIs. As the documentation for the built-in plugins seemed sparse, I found myself getting google hits for these other plugins, which is where the noise for APIs came in.
I'm not asking the main team to document others' plugins - but the distinction would be helpful to have clear.

The plugins I'm referring to are:
Inventree-part-import - took a while to install, but for docker, required me to get a console into the docker, use pip to install pipx (because pip would error-out), and then pipx install inventree-part-import. The text-based command-line interface on first run would be run, but the first time you run it you need to ensure you have all of your API keys together. When asked a plain prompt about cookies, it isn't yes/no, (although it accepts that input only to error-out later), it expects a browser to be entered. That would be nice to be prompted. My motivation for this plugin was to possibly text-import the list of items as scanning wasn't doing what I had hoped, but also to create the simple parts category scaffold as the Inventree application feature couldn't import his YAML file. @30350n
I recognize that installing the plugin this way would be transient, and likely not an ideal long-term solution. It had hoped it would help for a one-off utilization.

I didn't try KiNTree, as I don't currently use KiCad. I have been using Eagle sporatically. It looks like that one has more documentation and features fleshed out. I may look to see if I should just install KiCad to use the plugin. Adding another application still to learn to get on with the projects at hand felt like more of an obstacle than I wished to face at the time. I also wasn't too keen on disabling enforcing parameter checking for the plugin to work, possibly creating issues downstream.

Digikey-Inventree-Integration - required multiple installation steps of prerequisites for a docker installation. For bare-metal, this would have seemed simple. I am fairly new to docker, but this plugin didn't seem to have a way of being installed using the documentation in Inventree's plugins directory or txt file, but also I didn't see examples of how this should be working. These documentation discussed the API details needed (reasonable, as it is making a call), and as I thought the builtin plugin also made a call, I had translated it over.

This inventree page suggests the need for the API keys, although it is clearly referring to submitting information to the site for purchases. Of note, however, the main Inventree installation page suggests using docker to install, but this plugin installation is seeming to require a command-line access to a bare-metal install. Certainly could be due to a docker knowledge gap on my part.

It would be nice to have a more streamlined first-use documentation. Specifically, mentioning at the outset that using http (no https) even for internal installations will likely prevent you from using webcam barcode scanners on most browsers and prevent digikey api from being authenticated, so it would be good to bite the bullet and just use https. After initially using http, I then had later caddy config issues, with online documentation pointing to caddy:alpine2 solutions. it would have been much simpler to just use https. Pointing to a generic outside how-to for https could be helpful, possibly for LetsEncrypt or something similar. Either let caddy manage it, or set up a new inventree-proxy volume in docker-compose.yml similar to:

• ${INVENTREE_EXT_VOLUME}/caddy/certificates:/etc/caddy/certs:ro
  to let you copy your keys in to a volume that caddy can access.
  Given that (to me) it seems that https is pretty key, it seems that the volume would be good to include in a stock caddy install, and point out the location for keys to be placed.

Also in the inventree-proxy volumes section, it appears that numerous caddy locations are mapped to the same INVENTREE_EXT_VOLUME location without subfolders. I remapped them to subfolders, thinking they had been a part of my problems. My adaptation below, and compared against the stock docker-compose.yml
- ${INVENTREE_EXT_VOLUME}/caddy_data:/data:z
- ${INVENTREE_EXT_VOLUME}/caddy_config:/config:z
- ${INVENTREE_EXT_VOLUME}/caddy_logs:/var/log/caddy:z

The install page is pretty good for the most part otherwise, though.
My installation is somewhat chaotic, as in addition to docker/caddy, I also run an apache server using 443, and a tomcat server using another https port, so I needed to customize the port configuration and disable self-management of renewal to make them all play nice with eachother and my https certificates. This level of caddy configuration is beyond what would be reasonably expected of this documentation.

An overview page for subsequent (first) use would be helpful, however. To get started, you will likely need: .... (if you want to search Mouser/Digikey, you will need their search APIs, and these xyz plugins; if you want to submit orders, you will need their order APIs and xyz plugins/link to page; you will need to decide on a parts category system and set at least some of it up before you can add parts. If using for electronics parts, you could use inventree-part-import command line interface to import an example/basic system (or better yet, an example file(s) that can be uploaded within the native system in Inventree admin /platform/settings/admin/import - similar to what the inventree-part-import plugin offers.)

At the bottom of the parts page it does mention that parts can be imported by admins, and clicking through the page this involves a pre-populated csv file - so not quite helpful for first runs but more for data migration, it seems.

My use case is that of hobbyist who no longer has much free time, works entirely too much, and has several chaotic piles of parts that I'm working to categorise and store in an organised manner that hopefully I can find again. I don't have staff that I can set to scanning/populating data, unfortunately. I imagine everyone would benefit from streamlined pre-population of new parts, though. I would love an integration that allowed webcam or mobile app barcode scanning, search lookup on the supplier's website and pre-population of a new part page that I can accept/adapt as needed.
Perhaps I am wrong and larger installations want regular granular control of this data, or perhaps this already exists in an area I have overlooked.

Thanks for your patience with these new-user concerns and ?suggestions.

[wolflu05]

Sorry, I don't have the time to fully read your message, but you might be interested in #9761 . This adds a plugin interface for "importing" parts from a supplier.

[matmair]

The website does not contain docs for the system. Docs are housed here, together with the code.

I do not see us recommending external tools from our install docs, that would mean we had to make sure that those remain active and usable with InvenTree. Taking on that burden is probably not worth it.

[bdmartens]

Sorry, I don't have the time to fully read your message, but you might be interested in #9761 . This adds a plugin interface for "importing" parts from a supplier.

That looks promising. I look forward to the mixin becoming available!

[bdmartens]

The website does not contain docs for the system. Docs are housed here, together with the code.

I do not see us recommending external tools from our install docs, that would mean we had to make sure that those remain active and usable with InvenTree. Taking on that burden is probably not worth it.

I agree officially not recommending external plugins makes sense - but clearly distinguishing which features are NOT core seems to make sense (clarifying that the core barcode plugin does not enable search, just interpretation of the barcode - should this be correct).
I don't fully get your comment on the website not containing docs for the system. It seems to clearly contain a lot of docs for the system.

Also, incidentally, the new UI sidebar documentation section (0.17.14) at the bottom has two bad links to "page not found":
https://docs.inventree.org/en/latest/start/intro/
https://docs.inventree.org/en/latest/api/api/

[matmair]

Documenting what a software does not do is a fools errand. We document what the software can do, someone assuming that it does more is not enough for me to spend time on it.

You opened the issue in inventree/inventree-website - which is the code for InvenTree.org
The documentation that you reference is on docs.inventree.org - whose code is in inventree/inventree

It looks like you like to write text; it would be more beneficial to submit documentation improvements