mirror of
https://github.com/inventree/InvenTree.git
synced 2025-06-15 11:35:41 +00:00
Documentation integration (#4653)
* Add documentation under docs/ directory * Add CI workflow for mkdocs configuration checking * Add documentation issue template * update pip-tools? * Update .gitignore files * Fix .gitignore rules * Improve release notes page * remove references to old repo
This commit is contained in:
Oliver
GitHub
19
docs/docs/settings/MFA.md
Normal file
19
docs/docs/settings/MFA.md
Normal file
@ -0,0 +1,19 @@
|
||||
---
|
||||
title: InvenTree Multi Factor Authentication
|
||||
---
|
||||
|
||||
## Multi Factor Authentication
|
||||
|
||||
InvenTree gives the option to use TOTP or statically generated backup tokens as an additional factor to password or SSO authentication. This is a widely adopted security feature on enterprise web services. We highly encourage to enable it if you expose your instance to the public internet.
|
||||
|
||||
As TOTP is an [open standard](https://datatracker.ietf.org/doc/html/rfc6238) there are a lot of different ways to hold your key and generate the time based tokens needed for authentication. That ranges from physical devices to password managers and mobile apps. We do not advertise any method but recommend to keep password and token generator seperate from each other.
|
||||
|
||||
### Configuration
|
||||
|
||||
To make MFA mandatory for all users:
|
||||
|
||||
1. Enable it in the [global settings](../settings/global.md).
|
||||
|
||||
### Security Consideration
|
||||
|
||||
A user can lock themself out if they lose access to both the device with their TOTP app and their backup tokens. An admin can delete their tokens from the admin pages (they exist under the 'TOTP devices' / 'static devices' models) . This should be a last resort and only done by people knowledgeable about the [admin pages](../settings/admin.md) as changes there might circumvent InvneTrees buisness and security logic.
|
||||
127
docs/docs/settings/SSO.md
Normal file
127
docs/docs/settings/SSO.md
Normal file
@ -0,0 +1,127 @@
|
||||
---
|
||||
title: InvenTree Single Sign On
|
||||
---
|
||||
|
||||
## Single Sign On
|
||||
|
||||
InvenTree provides the possibility to use 3rd party services to authenticate users. This functionality makes use of [django-allauth](https://django-allauth.readthedocs.io/en/latest/) and supports a wide array of OpenID and OAuth [providers](https://django-allauth.readthedocs.io/en/latest/providers.html).
|
||||
|
||||
!!! tip "Provider Documentation"
|
||||
There are a lot of technical considerations when configuring a particular SSO provider. A good starting point is the [django-allauth documentation](https://django-allauth.readthedocs.io/en/latest/providers.html)
|
||||
|
||||
## SSO Configuration
|
||||
|
||||
The basic requirements for configuring SSO are outlined below:
|
||||
|
||||
1. Enable the required providers in the [config file](../start/config.md#single-sign-on).
|
||||
1. Create an external *app* with your provider of choice
|
||||
1. Add the required client configurations in the `SocialApp` app in the [admin interface](../settings/admin.md).
|
||||
1. Configure the *callback* URL for the external app.
|
||||
1. Enable SSO for the users in the [global settings](../settings/global.md).
|
||||
1. Configure [e-mail](../settings/email.md).
|
||||
|
||||
### Configuration File
|
||||
|
||||
The first step is to ensure that the required provider modules are installed, via your installation [configuration file](../start/config.md#single-sign-on).
|
||||
|
||||
There are two variables in the configuration file which define the operation of SSO:
|
||||
|
||||
| Key | Description | More Info |
|
||||
| --- | --- | --- |
|
||||
| `social_backends` | A *list* of provider backends enabled for the InvenTree instance | [django-allauth docs](https://django-allauth.readthedocs.io/en/latest/installation.html) |
|
||||
| `social_providers` | A *dict* of settings specific to the installed providers | [provider documentation](https://django-allauth.readthedocs.io/en/latest/providers.html) |
|
||||
|
||||
In the example below, SSO provider modules are activated for *google*, *github* and *microsoft*. Specific configuration options are specified for the *microsoft* provider module:
|
||||
|
||||
{% with id="SSO", url="settings/sso_config.png", description="SSO Config" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
!!! info "Provider Module Format"
|
||||
Note that the provider modules specified in `social_backends` must be prefixed with `allauth.socialaccounts.providers`
|
||||
|
||||
!!! tip "Restart Server"
|
||||
As the [configuration file](../start/config.md) is only read when the server is launched, ensure you restart the server after editing the file.
|
||||
|
||||
### Create Provider App
|
||||
|
||||
The next step is to create an external authentication app with your provider of choice. This step is wholly separate to your InvenTree installation, and must be performed before continuing further.
|
||||
|
||||
!!! info "Read the Documentation"
|
||||
The [django-allauth documentation](https://django-allauth.readthedocs.io/en/latest/providers.html) is a good starting point here. There are also a number of good tutorials online (at least for the major supported SSO providers).
|
||||
|
||||
In general, the external app will generate a *key* and *secret* pair - although different terminology may be used, depending on the provider.
|
||||
|
||||
### Add Client Configurations
|
||||
|
||||
Once your external SSO app has been created, you need to create a new *SocialAccount* client configuration (via the InvenTree admin interface).
|
||||
|
||||
#### Create Social Application
|
||||
|
||||
In the admin interface, select *Add Social Application*
|
||||
|
||||
{% with id="social-add", url="settings/social_account_add.png", description="Add Social Application" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
#### Configure Social Application
|
||||
|
||||
Configure the social application entry with the app details:
|
||||
|
||||
{% with id="social-configure", url="settings/social_application_configure.png", description="Configure Social Application" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
- Select the *provider* type as required
|
||||
- Provide a *name* for the application (note that this should match the *name* used for any custom settings provided in the configuration file)
|
||||
- Add client and secret data for your external SSO app
|
||||
- Add the *site* which you want to provide access for this SSO app
|
||||
- Save the new application entry when configuration is finished
|
||||
|
||||
!!! tip "Fix Your Mistakes"
|
||||
You can always return to edit or adjust the social application details later
|
||||
|
||||
!!! success "Multiple Applications"
|
||||
To provide support for multiple SSO applications, simply repeat this process and create another social application entry
|
||||
|
||||
### Configure Callback URL
|
||||
|
||||
The external SSO application must be provided with a *callback* URL - a URL by which it can communicate with the InvenTree server. The specific *name* that the external SSO application uses for this callback URL may vary, with some authentication applications referring to it with other names such as *reply* or *redirect*.
|
||||
|
||||
In any case, the URL is is specific to your installation and the SSO provider. The general pattern for this URL is: `{% raw %}<hostname>/accounts/<provider>/login/callback/{% endraw %}`.
|
||||
|
||||
!!! success "Works for Local Installs"
|
||||
Your server does not need to be "public facing" for this to work. For example the URL `http://localhost:1234/accounts/github/login/callback/` would be perfectly valid!
|
||||
|
||||
### Enable SSO Settings
|
||||
|
||||
Now that the social application is created, you need to enable SSO authentication for the InvenTree server.
|
||||
|
||||
In the [settings screen](./global.md), navigate to the *Login Settings* panel. Here you will see the required configuration options to enable SSO:
|
||||
|
||||
{% with id="sso-settings", url="settings/sso_settings.png", description="SSO Settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
| Setting | Description |
|
||||
| --- | --- |
|
||||
| Enable SSO | Enable this option to allow single sign on for user login |
|
||||
| Enable SSO registration | Allow users to self-register with SSO |
|
||||
| Auto-fill SSO users | Automatically fill out user account data with information provided by external SSO app |
|
||||
| Allowed domains | Optionally restrict signup to certain domains |
|
||||
|
||||
### Configure Email
|
||||
|
||||
Note that [email settings](./email.md) must be correctly configured before SSO will be activated. Ensure that your email setup is correctly configured and operataional.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
You should use SSL for your website if you want to use this feature. Also set your callback-endpoints to `https://` addresses to reduce the risk of leaking user's tokens.
|
||||
|
||||
Tokens for authenticating the users to the providers they registered with are saved in the database.
|
||||
So ensure your database is protected and not open to the internet.
|
||||
|
||||
Make sure all users with admin privileges have sufficient passwords - they can read out your client configurations with providers and all auth-tokens from users.
|
||||
|
||||
!!! warning "It's a secret!"
|
||||
Never share the secret key associated with your InvenTree install!
|
||||
56
docs/docs/settings/admin.md
Normal file
56
docs/docs/settings/admin.md
Normal file
@ -0,0 +1,56 @@
|
||||
---
|
||||
title: InvenTree Admin Interface
|
||||
---
|
||||
|
||||
## Admin Interface
|
||||
|
||||
Users which have *staff* privileges have access to an Admin interface which provides extremely low level control of the database. Every item in the database is available and this interface provides a convenient option for directly viewing and modifying database objects.
|
||||
|
||||
!!! warning "Caution"
|
||||
Admin users should exercise extreme care when modifying data via the admin interface, as performing the wrong action may have unintended consequences!
|
||||
|
||||
The admin interface allows *staff* users the ability to directly view / add / edit / delete database entries according to their [user permissions](./permissions.md).
|
||||
|
||||
### Access Admin Interface
|
||||
|
||||
To access the admin interface, select the "Admin" option from the drop-down user menu in the top-right corner of the screen.
|
||||
|
||||
|
||||
!!! info "Staff Only"
|
||||
Only users with staff acccess will be able to see the "Admin" option
|
||||
|
||||
An adminstation panel will be presented as shown below:
|
||||
|
||||
{% with id="admin", url="admin/admin.png", description="InvenTree Admin Panel" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
!!! info "Admin URL"
|
||||
To directly access the admin iterface, append /admin/ to the InvenTree site URL - e.g. http://localhost:8000/admin/
|
||||
|
||||
### View Database Objects
|
||||
|
||||
Database objects can be listed and filtered directly. The image below shows an example of displaying existing part categories.
|
||||
|
||||
{% with id="part_cats", url="admin/part_cats.png", description="Display part categories" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
!!! info "Permissions"
|
||||
A "staff" account does not necessarily provide access to all administration options, depending on the roles assigned to the user.
|
||||
|
||||
#### Filtering
|
||||
|
||||
Some admin views support filtering of results against specified criteria. For example, the list of Part objects can be filtered as follows:
|
||||
|
||||
{% with id="filter", url="admin/filter.png", description="Filter part list" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Edit Database Objects
|
||||
|
||||
Individual database objects can be edited directly in the admin interface. The image below shows an exmple of editing a Part object:
|
||||
|
||||
{% with id="edit_part", url="admin/edit_part.png", description="Edit Part object" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
12
docs/docs/settings/email.md
Normal file
12
docs/docs/settings/email.md
Normal file
@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Email Configured
|
||||
---
|
||||
|
||||
## Email Settings
|
||||
|
||||
InvenTree can be configured to send emails to users, for various purposes.
|
||||
|
||||
To enable this, email configuration settings must be supplied to the InvenTree [configuration options](../start/config.md#email-settings).
|
||||
|
||||
!!! info "Password Reset"
|
||||
The *Password Reset* functionality requires the email backend to be correctly configured.
|
||||
17
docs/docs/settings/export.md
Normal file
17
docs/docs/settings/export.md
Normal file
@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Exporting Data
|
||||
---
|
||||
|
||||
## Exporting Data
|
||||
|
||||
The Admin Interface provides powerful data exporting capability. When displaying a list of items which support exporting (e.g. Part objects), select the "Export" button from the top-right corner:
|
||||
|
||||
{% with id="export", url="admin/export.png", description="Data export" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
Multiple data formats are supported for exported data:
|
||||
|
||||
{% with id="formats", url="admin/formats.png", description="Data formats" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
193
docs/docs/settings/global.md
Normal file
193
docs/docs/settings/global.md
Normal file
@ -0,0 +1,193 @@
|
||||
---
|
||||
title: Global Settings
|
||||
---
|
||||
|
||||
## Global Settings
|
||||
|
||||
InvenTree ships with a lot of dynamic settings which can be configured at run-time. These settings are stored in the InvenTree database itself.
|
||||
|
||||
The following settings are *global* settings which affect all users.
|
||||
|
||||
!!! info "Staff Status Required"
|
||||
Only users with *staff* status can view and edit global settings
|
||||
|
||||
To edit global settings, select *Settings* from the menu in the top-right corner of the screen.
|
||||
|
||||
Global settings are arranged in the following categories:
|
||||
|
||||
### Server Settings
|
||||
|
||||
Configuration of basic server settings.
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| InvenTree Instance Name | String | String descriptor for the InvenTree server instance | InvenTree Server |
|
||||
| Use Instance Name | Boolean | Use instance name in title bars | False |
|
||||
| Restrict showing `about` | Boolean | Show the `about` modal only to superusers | False |
|
||||
| Base URL | String | Base URL for server instance | *blank* |
|
||||
| Company Name | String | Company name | My compant name |
|
||||
| Download from URL | Boolean | Allow downloading of images from remote URLs | False |
|
||||
|
||||
### Login Settings
|
||||
|
||||
Change how logins, password-forgot, signups are handled.
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Enable registration | Boolean | Enable self-registration for users on the login-pages | False |
|
||||
| Enable SSO | Boolean | Enable SSO on the login-pages | False |
|
||||
| Enable SSO registration | Boolean | Enable self-registration for users via SSO on the login-pages | False |
|
||||
| Enable password forgot | Boolean | Enable password forgot function on the login-pages.<br><br>This will let users reset their passwords on their own. For this feature to work you need to configure E-mail | True |
|
||||
| E-Mail required | Boolean | Require user to supply e-mail on signup.<br><br>Without a way (e-mail) to contact the user notifications and security features might not work! | False |
|
||||
| Enforce MFA | Boolean | Users must use multifactor security.<br><br>This forces each user to setup MFA and use it on each autentication | False |
|
||||
| Mail twice | Boolean | On signup ask users twice for their mail | False |
|
||||
| Password twice | Boolean | On signup ask users twice for their password | True |
|
||||
| Auto-fill SSO users | Boolean | Automatically fill out user-details from SSO account-data.<br><br>If this feature is enabled the user is only asked for their username, first- and surname if those values can not be gathered from their SSO profile. This might lead to unwanted usernames bleading over. | True |
|
||||
| Allowed domains | String | Restrict signup to certain domains (comma-separated, starting with @) | |
|
||||
|
||||
|
||||
### Barcodes
|
||||
|
||||
Configuration of barcode functionality
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Barcode Support | Boolean | Enable barcode functionality in web interface | True |
|
||||
|
||||
### Currencies
|
||||
|
||||
Configuration of currency support
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Default Currency | Currency | Default currency | USD |
|
||||
|
||||
### Reporting
|
||||
|
||||
Configuration of report generation
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Enable Reports | Boolean | Enable report generation | False |
|
||||
| Page Size | String | Default page size | A4 |
|
||||
| Debug Mode | Boolean | Generate reports in debug mode (HTML output) | False |
|
||||
| Test Reports | Boolean | Enable generation of test reports | False |
|
||||
|
||||
### Parts
|
||||
|
||||
#### Main Settings
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| IPN Regex | String | Regular expression pattern for matching Part IPN | *blank* |
|
||||
| Allow Duplicate IPN | Boolean | Allow multiple parts to share the same IPN | True |
|
||||
| Allow Editing IPN | Boolean | Allow changing the IPN value while editing a part | True |
|
||||
| Part Name Display Format | String | Format to display the part name | {% raw %}`{{ part.id if part.id }}{{ ' | ' if part.id }}{{ part.name }}{{ ' | ' if part.revision }}{{ part.revision if part.revision }}`{% endraw %} |
|
||||
| Show Price History | Boolean | Display historical pricing for Part | False |
|
||||
| Show Price in Forms | Boolean | Display part price in some forms | True |
|
||||
| Show Price in BOM | Boolean | Include pricing information in BOM tables | True |
|
||||
| Show related parts | Boolean | Display related parts for a part | True |
|
||||
| Create initial stock | Boolean | Create initial stock on part creation | True |
|
||||
|
||||
#### Creation Settings
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Template | Boolean | Parts are templates by default | False |
|
||||
| Assembly | Boolean | Parts can be assembled from other components by default | False |
|
||||
| Component | Boolean | Parts can be used as sub-components by default | True |
|
||||
| Trackable | Boolean | Parts are trackable by default | False |
|
||||
| Purchaseable | Boolean | Parts are purchaseable by default | True |
|
||||
| Salable | Boolean | Parts are salable by default | False |
|
||||
| Virtual | Boolean | Parts are virtual by default | False |
|
||||
|
||||
#### Copy Settings
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Copy Part BOM Data | Boolean | Copy BOM data by default when duplicating a part | True |
|
||||
| Copy Part Parameter Data | Boolean | Copy parameter data by default when duplicating a part | True |
|
||||
| Copy Part Test Data | Boolean | Copy test data by default when duplicating a part | True |
|
||||
| Copy Category Parameter Templates | Boolean | Copy category parameter templates when creating a part | True |
|
||||
|
||||
#### Internal Price Settings
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Internal Prices | Boolean | Enable internal prices for parts | False |
|
||||
| Internal Price as BOM-Price | Boolean | Use the internal price (if set) in BOM-price calculations | False |
|
||||
|
||||
#### Part Import Setting
|
||||
|
||||
This section of the part settings allows staff users to:
|
||||
|
||||
- import parts to InvenTree clicking the <span class="badge inventree add"><span class='fas fa-plus-circle'></span> Import Part</span> button
|
||||
- enable the ["Import Parts" tab in the part category view](../part/part.md#part-import).
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Show Import in Views | Boolean | Display the import wizard in some part views | True |
|
||||
|
||||
#### Part Parameter Templates
|
||||
|
||||
Refer to the section describing [how to create part parameter templates](../part/parameter.md#create-template).
|
||||
|
||||
### Categories
|
||||
|
||||
In this section of the settings, staff users can set a list of parameters associated to a part category.
|
||||
|
||||
To add a parameter to a part category:
|
||||
|
||||
1. select the category in the dropdown list
|
||||
2. click the <span class="badge inventree add"><span class='fas fa-plus-circle'></span> New Parameter</span> button on the top right
|
||||
3. fill out the "Create Category Parameter Template" form
|
||||
4. click the <span class="badge inventree confirm">Submit</span> button.
|
||||
|
||||
After a list of parameters is added to a part category and upon creation of a new part in this category, this list of parameters will be added by default to the new part.
|
||||
|
||||
### Stock
|
||||
|
||||
Configuration of stock item options
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Stock Expiry | Boolean | Enable stock expiry functionality | False |
|
||||
| Stock Stale Time | Days | Number of days stock items are considered stale before expiring | 90 |
|
||||
| Sell Expired Stock | Boolean | Allow sale of expired stock | False |
|
||||
| Build Expired Stock | Boolean | Allow building with expired stock | False |
|
||||
| Stock Ownership Control | Boolean | Enable ownership control functionality | False |
|
||||
|
||||
### Build Orders
|
||||
|
||||
Options for build orders
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Reference Pattern | String | Pattern for defining Build Order reference values | {% raw %}BO-{ref:04d}{% endraw %} |
|
||||
|
||||
### Purchase Orders
|
||||
|
||||
Options for purchase orders
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Reference Pattern | String | Pattern for defining Purchase Order reference values | {% raw %}PO-{ref:04d}{% endraw %} |
|
||||
|
||||
### Sales orders
|
||||
|
||||
Options for sales orders
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Reference Pattern | String | Pattern for defining Sales Order reference values | {% raw %}SO-{ref:04d}{% endraw %} |
|
||||
|
||||
### Plugin Settings
|
||||
|
||||
Change into what parts plugins can integrate into.
|
||||
|
||||
| Setting | Type | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| Enable URL integration | Boolean | Enable plugins to add URL routes | False |
|
||||
| Enable navigation integration | Boolean | Enable plugins to integrate into navigation | False |
|
||||
| Enable setting integration | Boolean | Enable plugins to integrate into inventree settings | False |
|
||||
| Enable app integration | Boolean | Enable plugins to add apps | False |
|
||||
91
docs/docs/settings/import.md
Normal file
91
docs/docs/settings/import.md
Normal file
@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Importing Data
|
||||
---
|
||||
|
||||
## Importing Data
|
||||
|
||||
External data can be imported via the admin interface, allowing for rapid integration of existing datasets, or bulk editing of table data.
|
||||
|
||||
!!! danger "Danger"
|
||||
Uploading bulk data directly is a non-reversible action.
|
||||
|
||||
!!! warning "Backup"
|
||||
Ensure you have made a backup of your database before performing bulk data import.
|
||||
|
||||
!!! warning "Supported Models"
|
||||
Not all models in the InvenTree database support bulk import actions.
|
||||
|
||||
When viewing a model (which supports bulk data import) in the admin interface, select the "Import" button in the top-right corner:
|
||||
|
||||
{% with id="import", url="admin/import.png", description="Data import" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
The next screen displays a list of column headings which are expected to be present in the uploaded data file.
|
||||
|
||||
{% with id="import_upload", url="admin/import_upload.png", description="Data upload" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
Select the data file to import, and the data format. Press the "Submit" button to upload the file.
|
||||
|
||||
### File Format
|
||||
|
||||
The uploaded data file must meet a number of formatting requirements for successful data upload. A simple way of ensuring that the file format is correct is to first [export data](./export.md) for the model in question, and delete all data rows (not the header row) from the exported data file.
|
||||
|
||||
Then, the same file can be used as a template for uploading more data to the server.
|
||||
|
||||
### ID Field
|
||||
|
||||
The uploaded data file requires a special field called `id`. This `id` field uniquely identifies each entry in the database table(s) - it is also known as a *primary key*.
|
||||
|
||||
The `id` column **must** be present in an uploaded data file, as it is required to know how to process the incoming data.
|
||||
|
||||
Depending on the value of the `id` field in each row, InvenTree will attempt to either insert a new record into the database, or update an existing one.
|
||||
|
||||
#### Empty ID
|
||||
|
||||
If the `id` field in a given data row is empty (blank), then InvenTree interprets that particular row as a *new* entry which will be inserted into the database.
|
||||
|
||||
If you wish for a new database entry to be created for a particular data row, the `id` field **must** be left blank for that row.
|
||||
|
||||
#### Non-Empty ID
|
||||
|
||||
If the `id` field in a given data row is *not* empty, then InvenTree inteprets that particular row as an *existing* row to override / update.
|
||||
|
||||
In this case, InvenTree will search the database for an entry with the matching `id`. If a matching entry is found, then the entry is updated with the provided data.
|
||||
|
||||
However, if an entry is *not* found with the matching `id`, InvenTree will return an error message, as it cannot find the matching database entry to update.
|
||||
|
||||
!!! warning "Check id Value"
|
||||
Exercise caution when uploading data with the `id` field specified!
|
||||
|
||||
### Import Preview
|
||||
|
||||
After the data file has been uploaded and validated, the user is presented with a *preview* screen, showing the records that will be inserted or updated in the database.
|
||||
|
||||
Here the user has a final chance to review the data upload.
|
||||
|
||||
Press the *Confirm Import* button to actually perform the import process and commit the data into the database.
|
||||
|
||||
{% with id="import_preview", url="admin/import_preview.png", description="Data upload preview" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
Note that *new* records are automatically assigned an `id` value.
|
||||
|
||||
## Import Errors
|
||||
|
||||
Manually importing data in a relational database is a complex process. You may be presented with an error message which describes why the data could not be imported.
|
||||
|
||||
The error message should contain enough information to manually edit the data file to fix the problem.
|
||||
|
||||
Any error messages are displayed per row, and you can hover the mouse over the particular error message to view specific error details:
|
||||
|
||||
{% with id="import_error", url="admin/import_error.png", description="Data upload error" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
|
||||
!!! info "Report Issue"
|
||||
If the error message does not provide enough information, or the error seems like a bug caused by InvenTree itself, report an [issue on Github](https://github.com/inventree/inventree/issues).
|
||||
29
docs/docs/settings/logs.md
Normal file
29
docs/docs/settings/logs.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Admin Shell
|
||||
---
|
||||
|
||||
## Error Logs
|
||||
|
||||
Any critical server error logs are recorded to the database, and can be viewed by staff users using the admin interface.
|
||||
|
||||
In the admin interface, select the "Errors" view:
|
||||
|
||||
{% with id="admin_error_link", url="admin/admin_errors_link.png", description="Admin errors" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
!!! info "URL"
|
||||
Alternatively, navigate to the error list view at /admin/error_report/error/
|
||||
|
||||
A list of error logs is presented.
|
||||
|
||||
{% with id="admin_error_logs", url="admin/admin_errors.png", description="Error logs" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
!!! info "Deleting Logs"
|
||||
Error logs should be deleted periodically
|
||||
|
||||
## Reporting Errors
|
||||
|
||||
Errors should be reported to the [InvenTree GitHub page](https://github.com/inventree/inventree/issues), and include the full error output as recorded to the error log.
|
||||
65
docs/docs/settings/permissions.md
Normal file
65
docs/docs/settings/permissions.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: User Permissions
|
||||
---
|
||||
|
||||
## Permissions
|
||||
|
||||
InvenTree provides access control to various features and data, by assigning each *user* to one (or more) *groups* which have multiple *roles* assigned.
|
||||
|
||||
!!! info "Superuser"
|
||||
The superuser account is afforded *all* permissions across an InvenTree intallation. This includes the admin interface, web interface, and API.
|
||||
|
||||
### User
|
||||
|
||||
A *user* is a single unique account with login credentials. By default, a user is not afforded *any* permissions, and the user must be assigned to the relevant group for the permissions to be assigned.
|
||||
|
||||
### Group
|
||||
|
||||
A *group* is a named set of zero or more users. Each group is assigned permissions against each possible role.
|
||||
|
||||
### Role
|
||||
|
||||
A *role* is a set of distinct permissions linked to a given subset of InvenTree functionality (more on this below).
|
||||
|
||||
## Roles
|
||||
|
||||
InvenTree functionality is split into a number of distinct roles. A group will have a set of permissions assigned to each of the following roles:
|
||||
|
||||
- **Admin** - The *admin* role is related to assigning user permissions.
|
||||
- **Part Category** - The *part category* role is related to accessing Part Category data
|
||||
- **Part** - The *part* role is related to accessing Part data
|
||||
- **Stock Location** - The *stock location* role is related to accessing Stock Location data
|
||||
- **Stock Item** - The *stock item* role is related to accessing Stock Item data
|
||||
- **Build** - The *build* role is related to accessing Build Order and Bill of Materials data
|
||||
- **Purchase Order** - The *purchase* role is related to accessing Purchase Order data
|
||||
- **Sales Order** - The *sales* role is related to accessing Sales Order data
|
||||
- **Return Order** - The *return* role is related to accessing Return Order data
|
||||
|
||||
{% with id="Roles Admin View", url="admin/roles.png", description="Roles" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Role Permissions
|
||||
|
||||
Within each role, there are four levels of available permissions:
|
||||
|
||||
- **View** - The *view* permission allows viewing of content related to the particular role
|
||||
- **Change** - The *change* permission allows the user to edit / alter / change data associated with the particular role
|
||||
- **Add** - The *add* permission allows the user to add / create database records associated with the particular role
|
||||
- **Delete** - The *delete* permission allows the user to delete / remove database records associated with the particular role
|
||||
|
||||
## Admin Interface Permissions
|
||||
|
||||
If a user does not have the required permissions to perform a certain action in the admin interface, those options not be displayed.
|
||||
|
||||
If a user is expecting a certain option to be available in the admin interface, but it is not present, it is most likely the case that the user does not have those permissions assigned.
|
||||
|
||||
## Web Interface Permissions
|
||||
|
||||
When using the InvenTree web interface, certain functions may not be available for a given user, depending on their permissions. In this case, user-interface elements may be disabled, or may be removed.
|
||||
|
||||
## API Permissions
|
||||
|
||||
When using the InvenTree API, certain endpoints or actions may be inaccessible for a given user, depending on their permissions.
|
||||
|
||||
As the API is used extensively within the web interface, this means that many data tables may also be impacted by user permissions.
|
||||
51
docs/docs/settings/reference.md
Normal file
51
docs/docs/settings/reference.md
Normal file
@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Reference Patterns
|
||||
---
|
||||
|
||||
## Reference Patterns
|
||||
|
||||
InvenTree contains a number of data models which require a *unique* reference field (such as [Purchase Orders](../buy/po.md)). In addition to being *unique* these reference values must conform to a specific *pattern* (which can be defined by the user). Defined reference patterns also make it simple for the user to control how references are generated.
|
||||
|
||||
### Default Patterns
|
||||
|
||||
Out of the box, InvenTree defines a standard "pattern" for each type of reference (which can be edited via the InvenTree [settings interface](./global.md)).
|
||||
|
||||
| Model Type | Default Pattern | Example Output |
|
||||
| --- | --- | --- |
|
||||
| Purchase Order | `{% raw %}PO-{ref:04d}{% endraw %}` | PO-0001 |
|
||||
| Sales Order | `{% raw %}SO-{ref:04d}{% endraw %}` | SO-0123 |
|
||||
| Build Order | `{% raw %}BO-{ref:04d}{% endraw %}` | BO-1234 |
|
||||
| Return Order | `{% raw %} RMA-{ref:04d}{% endraw %}` | RMA-0987 |
|
||||
|
||||
### Pattern Requirements
|
||||
|
||||
Patterns can contain a mixture of literal strings, named variable blocks, and wildcard characters:
|
||||
|
||||
- The pattern **must** contain a single `{% raw %}{ref}{% endraw %}` variable - this is the required sequential part of the pattern
|
||||
- A `?` (question mark) character is treated as a wildcard which will match any character
|
||||
- A `#` (hash) character is treated as a wildcard which will match any digit `0-9`
|
||||
- Any other characters will be matched literally
|
||||
|
||||
### Variables
|
||||
|
||||
When building a reference, the following variables are available for use:
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
| `{% raw %}{ref}{% endraw %}` | Incrementing portion of the reference (**required*)). Determines which part of the reference field auto-increments |
|
||||
| `{% raw %}{date}{% endraw %}` | The current date / time. This is a [Python datetime object](https://docs.python.org/3/library/datetime.html#datetime.datetime.now) |
|
||||
|
||||
The reference field pattern uses <a href="https://www.w3schools.com/python/ref_string_format.asp">Python string formatting</a> for value substitution.
|
||||
|
||||
!!! tip "Date Formatting"
|
||||
The `{% raw %}{date}{% endraw %}` variable can be formatted using the [Python Format Codes](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior).
|
||||
|
||||
#### Substitution Examples
|
||||
|
||||
Some examples below demonstrate how the variable substitution can be implemented:
|
||||
|
||||
| Pattern | Description | Example Output |
|
||||
| --- | --- | --- |
|
||||
| `{% raw %}PO-{ref}{% endraw %}` | Render the *reference* variable without any custom formatting | PO-123 |
|
||||
| `{% raw %}PO-{ref:05d}{% endraw %}` | Render the *reference* variable as a 5-digit decimal number | PO-00123 |
|
||||
| `{% raw %}PO-{ref:05d}-{date:%Y-%m-%d}{% endraw %}` | Render the *date* variable in isoformat | PO-00123-2023-01-17 |
|
||||
29
docs/docs/settings/tasks.md
Normal file
29
docs/docs/settings/tasks.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Background Tasks
|
||||
---
|
||||
|
||||
## Background Tasks
|
||||
|
||||
In addition to managing the database and providing a web interface, InvenTree runs various background tasks;
|
||||
|
||||
### Blocking Operations
|
||||
|
||||
Some tasks (such as sending emails or performing bulk database actions) may take a significant amount of time. Instead of delaying the response to the user, these tasks are handled by the background task manager.
|
||||
|
||||
### Periodic Tasks
|
||||
|
||||
Some tasks must be performed on a regular, periodic basis.
|
||||
|
||||
## Django Q
|
||||
|
||||
InvenTree uses the [django-q](https://django-q.readthedocs.io/en/latest/) background task manager.
|
||||
|
||||
### Running Worker
|
||||
|
||||
The Django Q work must run separately to the web server. This is started as a separate process, as part of the InvenTree installation instructions.
|
||||
|
||||
If the worker is not running, a warning indicator is displayed in the InvenTree menu bar.
|
||||
|
||||
## Admin Interface
|
||||
|
||||
Scheduled tasks can be viewed in the InvenTree admin interface.
|
||||
55
docs/docs/settings/user.md
Normal file
55
docs/docs/settings/user.md
Normal file
@ -0,0 +1,55 @@
|
||||
---
|
||||
title: User Settings
|
||||
---
|
||||
|
||||
## User Settings
|
||||
|
||||
The various user settings described below can be configured for an individual user, to provide an InvenTree user experienced customized to their preferences. Your user settings can be accessed by selecting *Settings* from the menu in the top right order of the screen.
|
||||
|
||||
### Account Settings
|
||||
|
||||
The *Account Settings* screen shows configuration options for your user account, including linking [third party logins](./SSO.md) and [multi factor authentication](./MFA.md):
|
||||
|
||||
{% with id="user-account", url="settings/user_account.png", description="User Account Settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Display Settings
|
||||
|
||||
The *Display Settings* screen shows general display configuration options. Additionally, this screen allows the user to select the primary language in which InvenTree is displayed.
|
||||
|
||||
{% with id="user-display", url="settings/user_display.png", description="User Display Settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Home Page
|
||||
|
||||
This screen allows the user to customize display of items on the InvenTree home page.
|
||||
|
||||
{% with id="user-home", url="settings/user_home.png", description="Home Page Settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Search Settings
|
||||
|
||||
Customize settings for search results
|
||||
|
||||
{% with id="user-search", url="settings/user_search.png", description="User Search Settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Notifications
|
||||
|
||||
Settings related to notification messages
|
||||
|
||||
{% with id="user-notification", url="settings/user_notifications.png", description="User Notification Settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Reporting
|
||||
|
||||
Settings for label printing and report generation
|
||||
|
||||
{% with id="user-reporting", url="settings/user_reporting.png", description="User Reporting Settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
Reference in New Issue
Block a user