mirror of
https://github.com/inventree/InvenTree.git
synced 2026-05-28 03:49:20 +00:00
[docs] Update documentation (#11997)
* Rearrange import / export docs * Additional data export docs * Additional docs for custom states * Fix broken links
This commit is contained in:
Oliver
GitHub
@@ -4,17 +4,70 @@ title: Custom States
|
||||
|
||||
## Custom States
|
||||
|
||||
Several models within InvenTree support the use of custom states. The custom states are display only - the business logic is not affected by the state.
|
||||
Several models within InvenTree support the use of *custom states*. Custom states extend the built-in status system by adding extra labels and colours that are displayed in the user interface.
|
||||
|
||||
States can be added in the [Admin Center](../settings/admin.md#admin-center) under the "Custom States" section. Each state has a name, label and a color that are used to display the state in the user interface. Changes to these settings will only be reflected in the user interface after a full reload of the interface.
|
||||
!!! info "Display Only"
|
||||
Custom states affect display only — they do not add new workflow steps or change business logic. Every custom state is mapped to an existing built-in state (its *logical key*), and the system uses that built-in state for all decisions such as availability counts, order transitions, and filtering.
|
||||
|
||||
States need to be assigned to a model, state (for example status on a StockItem) and a logical key - that will be used for business logic. These 3 values combined need to be unique throughout the system.
|
||||
### Example
|
||||
|
||||
Custom states can be defined for the following models:
|
||||
Suppose you want to track stock items that are physically present and available, but are waiting for a quality inspection before use. The built-in `OK` status is the closest match — the item is available — but you want it to appear distinctly in the interface.
|
||||
|
||||
- [Stock Item](../stock/index.md)
|
||||
- [Build Order](../manufacturing/build.md)
|
||||
- [Purchase Order](../purchasing/purchase_order.md)
|
||||
- [Sales Order](../sales/sales_order.md)
|
||||
- [Return Order](../sales/return_order.md)
|
||||
- [Transfer Order](../stock/transfer_order.md)
|
||||
You would create a custom state:
|
||||
|
||||
- **Logical key**: `OK` — the system treats the item as available stock
|
||||
- **Label**: `Awaiting Inspection` — shown in the interface instead of "OK"
|
||||
- **Colour**: `warning` — displayed in amber to draw attention
|
||||
|
||||
The item is counted as available stock in all reports and filters, but is visually distinguished from items with a standard `OK` status.
|
||||
|
||||
## Managing Custom States
|
||||
|
||||
Custom states are managed in the [Admin Center](../settings/admin.md#admin-center) under the *Custom States* section.
|
||||
|
||||
!!! warning "Page Reload Required"
|
||||
Changes to custom states are only reflected in the user interface after a full page reload.
|
||||
|
||||
## State Fields
|
||||
|
||||
When creating a custom state, the following fields must be provided:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Model** | The model type this state applies to (e.g. *Stock Item*, *Build Order*) |
|
||||
| **Reference Status** | The status class being extended (e.g. `StockStatus`, `BuildStatus`) |
|
||||
| **Logical Key** | The built-in status value this custom state maps to for business logic |
|
||||
| **Key** | A unique integer that identifies this custom state in the database |
|
||||
| **Name** | An uppercase Python identifier for this state (e.g. `AWAITING_INSPECTION`) |
|
||||
| **Label** | The human-readable text displayed in the interface |
|
||||
| **Colour** | The badge colour used to display the state |
|
||||
|
||||
### Key
|
||||
|
||||
The *Key* is the integer value stored in the database when this custom state is active. It must satisfy all of the following:
|
||||
|
||||
- Must be a positive integer
|
||||
- Must not be equal to the *Logical Key*
|
||||
- Must not conflict with any existing built-in status values for the selected model
|
||||
|
||||
### Name
|
||||
|
||||
The *Name* field is used internally to identify the state. It must:
|
||||
|
||||
- Be uppercase (e.g. `AWAITING_INSPECTION`, not `awaiting_inspection`)
|
||||
- Be a valid Python identifier (letters, digits, underscores; no spaces or hyphens)
|
||||
- Not conflict with any existing status names for the selected model
|
||||
|
||||
### Colours
|
||||
|
||||
The following colour values are available:
|
||||
|
||||
| Colour | Appearance |
|
||||
|--------|------------|
|
||||
| `primary` | Blue |
|
||||
| `secondary` | Grey |
|
||||
| `success` | Green |
|
||||
| `warning` | Amber |
|
||||
| `danger` | Red |
|
||||
| `info` | Cyan |
|
||||
| `dark` | Dark grey / black |
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: Exporting Data
|
||||
---
|
||||
|
||||
## Exporting Data
|
||||
|
||||
InvenTree provides data export functionality for a variety of data types. Most data tables in the web interface include a *Download* button in the table toolbar, which allows the currently displayed data to be exported to a file.
|
||||
|
||||
!!! info "Filtered Data"
|
||||
The export reflects the data currently visible in the table — any active filters, search terms, or sort order are carried through to the exported file. To export the full dataset, clear all filters before exporting.
|
||||
|
||||
!!! info "Paginated Data"
|
||||
In the user interface, data tables are paginated to improve performance. When exporting data, the export will include **all** records that match the current filters and search terms, not just the records visible on the current page.
|
||||
|
||||
## How to Export
|
||||
|
||||
**Step 1** — In any table view, click the {{ icon("cloud-download") }} *Download* button in the table toolbar:
|
||||
|
||||
{{ image("admin/export.png", "Download button") }}
|
||||
|
||||
**Step 2** — An export dialog is displayed. Select the desired *Export Format* and *Export Plugin*, then click *Export*:
|
||||
|
||||
{{ image("admin/export_options.png", "Export dialog") }}
|
||||
|
||||
**Step 3** — The export runs in the background. A loading indicator is shown while the export is being processed. When the export is complete, the file is automatically downloaded to your browser.
|
||||
|
||||
## Supported File Formats
|
||||
|
||||
The following file formats are available for export:
|
||||
|
||||
| Format | Description |
|
||||
|--------|-------------|
|
||||
| CSV | Comma-separated values. Portable plain-text format, compatible with most tools. |
|
||||
| Excel | Microsoft Excel format (`.xlsx`). Suitable for direct use in spreadsheet applications. |
|
||||
| TSV | Tab-separated values. Similar to CSV but uses tab characters as delimiters. |
|
||||
|
||||
## Export Plugins
|
||||
|
||||
InvenTree uses a plugin-based export system. The export dialog lists all plugins that are available for the data type being exported. Selecting a different plugin may provide additional export options or a different output format.
|
||||
|
||||
### Built-in Exporters
|
||||
|
||||
InvenTree includes the following built-in export plugins:
|
||||
|
||||
| Plugin | Description |
|
||||
|--------|-------------|
|
||||
| [InvenTree Exporter](../plugins/builtin/inventree_exporter.md) | General-purpose exporter for any tabulated dataset. Always enabled. |
|
||||
| [BOM Exporter](../plugins/builtin/bom_exporter.md) | Custom exporter for Bill of Materials data, with additional BOM-specific options. |
|
||||
| [Parameter Exporter](../plugins/builtin/parameter_exporter.md) | Exports part data including all associated custom parameter values as additional columns. |
|
||||
| [Stocktake Exporter](../plugins/builtin/stocktake_exporter.md) | Exports a comprehensive stock-level summary for parts, with optional pricing and variant data. |
|
||||
|
||||
Custom export plugins can also be developed using the [DataExportMixin](../plugins/mixins/export.md).
|
||||
|
||||
## API Export
|
||||
|
||||
Data can also be exported programmatically via the InvenTree REST API. To trigger an export, perform a `GET` request against any list endpoint with the following query parameters:
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `export` | Set to `true` to trigger an export |
|
||||
| `export_format` | File format: `csv`, `xlsx`, or `tsv` (default: `csv`) |
|
||||
| `export_plugin` | Slug of the export plugin to use (default: `inventree-exporter`) |
|
||||
|
||||
Additional `export_*` parameters may be accepted depending on the plugin selected.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
GET /api/part/?export=true&export_format=xlsx&export_plugin=inventree-exporter
|
||||
```
|
||||
|
||||
Refer to the [API documentation](../api/index.md) for further details.
|
||||
@@ -43,7 +43,7 @@ Importing data is a multi-step process, which is managed via an *import session*
|
||||
|
||||
The import session is managed by the InvenTree server, and all import session data is stored on the server. As the import process can be time-consuming, the user can navigate away from the import page and return later to check on the progress of the import.
|
||||
|
||||
Import sessions can be managed from the [Admin Center](./admin.md#admin-center) page, which lists all available import sessions
|
||||
Import sessions can be managed from the [Admin Center](../settings/admin.md#admin-center) page, which lists all available import sessions
|
||||
|
||||
### Context Sensitive Importing
|
||||
|
||||
@@ -55,9 +55,9 @@ An import session can be initiated from a number of different contexts within th
|
||||
|
||||
### Admin Center
|
||||
|
||||
Staff users can create an import session from within the [Admin Center](./admin.md#admin-center). This is a general-purpose import session, and the user will be required to select the type of data to import.
|
||||
Staff users can create an import session from within the [Admin Center](../settings/admin.md#admin-center). This is a general-purpose import session, and the user will be required to select the type of data to import.
|
||||
|
||||
Users can quickly navigate to the data import managemement page from the [spotlight search](../concepts/user_interface.md#spotlight), by searching for "import" and selecting the "Import data" option.
|
||||
Users can quickly navigate to the data import management page from the [spotlight search](../concepts/user_interface.md#spotlight), by searching for "import" and selecting the "Import data" option.
|
||||
|
||||
### Data Tables
|
||||
|
||||
@@ -123,7 +123,7 @@ The basic outline of this process is:
|
||||
### Create Import Session
|
||||
|
||||
!!! note "Admin Center"
|
||||
Updating existing records can only be performed when creating a new import session from the [Admin Center](./admin.md#admin-center).
|
||||
Updating existing records can only be performed when creating a new import session from the [Admin Center](../settings/admin.md#admin-center).
|
||||
|
||||
Create a new import session, and ensure that the *Update Existing Records* option is selected. This will allow the import session to update existing records in the database.
|
||||
|
||||
@@ -118,7 +118,7 @@ By default, the BOM is displayed in "view" mode. To edit the BOM, click on the {
|
||||
|
||||
### Importing a BOM
|
||||
|
||||
BOM data can be imported from an existing file (such as CSV or Excel) from the *BOM* panel for a particular part/assembly. This process is a special case of the more general [data import process](../settings/import.md).
|
||||
BOM data can be imported from an existing file (such as CSV or Excel) from the *BOM* panel for a particular part/assembly. This process is a special case of the more general [data import process](../concepts/data_import.md).
|
||||
|
||||
At the top of the *BOM* panel, click on the {{ icon("file-arrow-left", color="green", title="Import BOM Data") }} icon to open the import dialog.
|
||||
|
||||
|
||||
@@ -48,7 +48,7 @@ If the *Add Supplier Data* option is checked, then supplier part and manufacture
|
||||
|
||||
Parts can be imported from an external file, by selecting the *Import from File* option.
|
||||
|
||||
This action opens the [data import wizard](../settings/import.md), which steps the user through the process of importing parts from the selected file.
|
||||
This action opens the [data import wizard](../concepts/data_import.md), which steps the user through the process of importing parts from the selected file.
|
||||
|
||||
## Import from Supplier
|
||||
|
||||
|
||||
@@ -160,4 +160,4 @@ The [InvenTree mobile app](../app/part.md#part-image-view) allows part images to
|
||||
|
||||
## Part Import
|
||||
|
||||
*Parts* can be imported by staff-members on the part-list-view (this feature must be enabled in the part-settings), in the part-settings or on the [admin-page for parts](../settings/import.md) (only accessible if you are also an admin). The first two options provide a multi-stage wizard that enables mapping fields from various spreadsheet or table-data formats while the latter requires a well-formatted file but is much more performant.
|
||||
*Part* data can be imported using the [data import wizard](../concepts/data_import.md). This allows part data to be imported from an external file, which can be useful for bulk importing of part data.
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: Exporting Data
|
||||
---
|
||||
|
||||
## Exporting Data
|
||||
|
||||
InvenTree provides data export functionality for a variety of data types. Most data tables provide an "Download" button, which allows the user to export the data in a variety of formats.
|
||||
|
||||
In the top right corner of the table, click the "Download" button to export the data in the table.
|
||||
|
||||
{{ image("admin/export.png", "Download") }}
|
||||
|
||||
This will present a dialog box with the available export options:
|
||||
|
||||
{{ image("admin/export_options.png", "Export Dialog") }}
|
||||
|
||||
## Plugin Support
|
||||
|
||||
InvenTree plugins can also provide custom export functionality for specific data types. If a plugin provides export functionality, it will be listed in the export options.
|
||||
|
||||
Refer to the [export plugin mixin documentation](../plugins/mixins/export.md) for more information on how to create export plugins.
|
||||
|
||||
## API Export
|
||||
|
||||
Data can also be exported via the InvenTree REST API, by appending the appropriate format suffix (and other export options) to the API endpoint URL.
|
||||
+2
-2
@@ -96,6 +96,8 @@ nav:
|
||||
- Physical Units: concepts/units.md
|
||||
- Companies: concepts/company.md
|
||||
- Custom States: concepts/custom_states.md
|
||||
- Data Export: concepts/data_export.md
|
||||
- Data Import: concepts/data_import.md
|
||||
- Pricing: concepts/pricing.md
|
||||
- Project Codes: concepts/project_codes.md
|
||||
- Attachments: concepts/attachments.md
|
||||
@@ -186,8 +188,6 @@ nav:
|
||||
- Multi Factor Authentication: settings/MFA.md
|
||||
- Email Settings: settings/email.md
|
||||
- Experimental Features: settings/experimental.md
|
||||
- Export Data: settings/export.md
|
||||
- Import Data: settings/import.md
|
||||
- Operations:
|
||||
- Background Tasks: settings/tasks.md
|
||||
- Error Logs: settings/logs.md
|
||||
|
||||
Reference in New Issue
Block a user