Added documentation for part provider system

README.md

@@ -51,6 +51,7 @@ Two-factor authentication is supported (Google Authenticator and Webauthn/U2F ke
 * Support for multiple currencies and automatic update of exchange rates supported
 * Powerful search and filter function, including parametric search (search for parts according to some specifications)
 * Automatic thumbnail generation for pictures
+* Use cloud providers (like Digikey, farnell or TME) to automatically get part information, datasheets and prices for parts
 
 
 With these features Part-DB is useful to hobbyists, who want to keep track of their private electronic parts inventory,

docs/configuration.md

@@ -74,6 +74,9 @@ You can find more advanced settings in the `config/packages/hslavich_onelogin_sa
 * `SAML_SP_X509_CERT`: The public X.509 certificate of your SAML SP (here Part-DB). This is the value you have configured for the Part-DB client in your IdP. It should start with `MIIC` and end with `=`. IdPs like keycloak allows you to generate a public/private key pair for the client which you can setup here and in the `SAML_SP_PRIVATE_KEY` setting.
 * `SAML_SP_PRIVATE_KEY`: The private key of your SAML SP (here Part-DB), corresponding the public key specified in `SAML_SP_X509_CERT`. This is the value you have configured for the Part-DB client in your IdP. It should start with `MIIE` and end with `=`. IdPs like keycloak allows you to generate a public/private key pair for the client which you can setup here and in the `SAML_SP_X509_CERT` setting.
 
+### Information provider settings
+The settings prefixes with `PROVIDER_*` are used to configure the information providers.
+See the [information providers]({% link usage/information_provider_system.md %}) page for more information.
 
 ### Other / less used options
 * `TRUSTED_PROXIES`: Set the IP addresses (or IP blocks) of trusted reverse proxies here. This is needed to get correct IP informations (see [here](https://symfony.com/doc/current/deployment/proxies.html) for more info).

docs/index.md

@@ -37,6 +37,7 @@ It is installed on a web server and so can be accessed with any browser without
 * Support for multiple currencies and automatic update of exchange rates supported
 * Powerful search and filter function, including parametric search (search for parts according to some specifications)
 * Easy migration from an existing PartKeepr instance (see [here]({%link partkeepr_migration.md %}))
+* Use cloud providers (like Digikey, farnell or TME) to automatically get part information, datasheets and prices for parts (see [here]({% link usage/information_provider_system.md %}))
 
 With these features Part-DB is useful to hobbyists, who want to keep track of their private electronic parts inventory,
 or makerspaces, where many users have should have (controlled) access to the shared inventory.

docs/usage/information_provider_system.md

@@ -0,0 +1,88 @@
+---
+title: Information provider system
+layout: default
+parent: Usage
+---
+
+# Information provider system
+
+Part-DB can create parts based on information from external sources: For example with the right setup you can just search for a part number
+and Part-DB will query selected distributors and manufacturers for the part and create a part with the information it found.
+This way your Part-DB parts automatically get datasheet links, prices, parameters and more, with just a few clicks.
+
+## Usage
+
+Before you can use the information provider system, you have to configure at least one information provider, which act as data source.
+See below for a list of available information providers and available configuration options.
+For many providers it is enough, to setup the API keys in the env configuration, some require an additional OAuth connection.
+You can list all enabled information providers in the browser at `https://your-partdb-instance.tld/tools/info_providers/providers` (you need the right permission for it, see below).
+
+To use the information provider system, your user need to have the right permissions. Go to the permission management page of 
+a user or a group and assign the permissions of the "Info providers" group in the "Miscellaneous" tab.
+
+If you have the required permission you will find in the sidebar in the "Tools" section the entry "Create part from info provider".
+Click this and you will land on a search page. Enter the part number you want to search for and select the information providers you want to use. 
+
+After you click Search, you will be presented with the results and can select the result that fits best. 
+With a click on the blue plus button, you will be redirected to the part creation page with the information already filled in.
+
+![image]({% link assets/usage/information_provider_system/animation.gif %})
+
+## Data providers
+
+The system tries to be as flexible as possible, so many different information sources can be used.
+Each information source is called am "info provider" and handles the communication with the external source.
+The providers are just a driver which handles the communication with the different external sources and converts them into a common format Part-DB understands.
+That way it is pretty easy to create new providers as they just need to do very little work.
+
+Normally the providers utilize an API of a service, and you need to create a account at the provider and get an API key. 
+Also there are limits on how many requests you can do per day or months, depending on the provider and your contract with them.
+
+The following providers are currently available and shipped with Part-DB:
+
+### Digi-Key
+The Digi-Key provider uses the [Digi-Key API](https://developer.digikey.com/) to search for parts and getting shopping information from [Digi-Key](https://www.digikey.com/).
+To use it you have to create an account at Digi-Key and get an API key on the [Digi-Key API page](https://developer.digikey.com/). 
+You must create an organization there and create a "Production app". Most settings are not important, you just have to grant access to the "Product Information" API.
+You will get an Client ID and a Client Secret, which you have to enter in the Part-DB env configuration (see below).
+
+Following env configuration options are available:
+* `PROVIDER_DIGIKEY_CLIENT_ID`: The client ID you got from Digi-Key (mandatory)
+* `PROVIDER_DIGIKEY_CLIENT_SECRET`: The client secret you got from Digi-Key (mandatory)
+* `PROVIDER_DIGIKEY_CURRENCY`: The currency you want to get prices in (optional, default: `EUR`)
+* `PROVIDER_DIGIKEY_LANGUAGE`: The language you want to get the descriptions in (optional, default: `en`)
+* `PROVIDER_DIGIKEY_COUNTRY`: The country you want to get the prices for (optional, default: `DE`)
+
+The Digi-Key provider needs an additional OAuth connection. To do this, go to the information provider list (`https://your-partdb-instance.tld/tools/info_providers/providers`), 
+go the Digi-Key provider (in the disabled page) and click on the "Connect OAuth" button. You will be redirected to Digi-Key, where you have to login and grant access to the app.
+To do this your user needs the "Manage OAuth tokens" permission from the "System" section in the "System" tab.
+The OAuth connection should only be needed once, but if you have any problems with the provider, just click the button again, to establish a new connection.
+
+### TME
+The TME provider use the API of [TME](https://www.tme.eu/) to search for parts and getting shopping information from them.
+To use it you have to create an account at TME and get an API key on the [TME API page](https://developers.tme.eu/en/).
+You have to generate a new anonymous key there and enter the key and secret in the Part-DB env configuration (see below).
+
+Following env configuration options are available:
+* `PROVIDER_TME_API_KEY`: The API key you got from TME (mandatory)  
+* `PROVIDER_TME_API_SECRET`: The API secret you got from TME (mandatory)
+* `PROVIDER_TME_CURRENCY`: The currency you want to get prices in (optional, default: `EUR`)
+* `PROVIDER_TME_LANGUAGE`: The language you want to get the descriptions in (`en`, `de` and `pl`) (optional, default: `en`)
+* `PROVIDER_TME_COUNTRY`: The country you want to get the prices for (optional, default: `DE`)
+* `PROVIDER_TME_GET_GROSS_PRICES`: If this is set to `1` the prices will be gross prices (including tax), otherwise net prices (optional, default: `0`)
+
+### Farnell / Element14 / Newark
+The Farnell provider uses the [Farnell API](https://partner.element14.com/) to search for parts and getting shopping information from [Farnell](https://www.farnell.com/).
+You have to create an account at Farnell and get an API key on the [Farnell API page](https://partner.element14.com/). 
+Register a new application there (settings does not matter, as long as you select the "Product Search API") and you will get an API key.
+
+Following env configuration options are available:
+* `PROVIDER_ELEMENT14_KEY`: The API key you got from Farnell (mandatory)
+* `PROVIDER_ELEMENT14_STORE_ID`: The store ID you want to use. This decides the language of results, currency and country of prices (optional, default: `de.farnell.com`, see [here](https://partner.element14.com/docs/Product_Search_API_REST__Description) for availailable values)
+
+
+### Custom provider
+To create a custom provider, you have to create a new class implementing the `InfoProviderInterface` interface. As long as it is a valid Symfony service, it will be automatically loaded and can be used.
+Besides some metadata functions, you have to implement the `searchByKeyword()` and `getDetails()` functions, which do the actual API requests and return the information to Part-DB.
+See the existing providers for examples.
+If you created a new provider, feel free to create a pull request to add it to the Part-DB core.