From 6530052471d812dcc9a1cdf00c9694c50b22a587 Mon Sep 17 00:00:00 2001 From: Oliver Date: Sun, 24 May 2026 10:05:06 +1000 Subject: [PATCH] [docs] Update documentation (#11997) * Rearrange import / export docs * Additional data export docs * Additional docs for custom states * Fix broken links --- docs/docs/concepts/custom_states.md | 73 ++++++++++++++++--- docs/docs/concepts/data_export.md | 72 ++++++++++++++++++ .../import.md => concepts/data_import.md} | 8 +- docs/docs/manufacturing/bom.md | 2 +- docs/docs/part/create.md | 2 +- docs/docs/part/index.md | 2 +- docs/docs/settings/export.md | 25 ------- docs/mkdocs.yml | 4 +- 8 files changed, 144 insertions(+), 44 deletions(-) create mode 100644 docs/docs/concepts/data_export.md rename docs/docs/{settings/import.md => concepts/data_import.md} (93%) delete mode 100644 docs/docs/settings/export.md diff --git a/docs/docs/concepts/custom_states.md b/docs/docs/concepts/custom_states.md index 1244939507..7a60701470 100644 --- a/docs/docs/concepts/custom_states.md +++ b/docs/docs/concepts/custom_states.md @@ -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 | diff --git a/docs/docs/concepts/data_export.md b/docs/docs/concepts/data_export.md new file mode 100644 index 0000000000..bb5a20f369 --- /dev/null +++ b/docs/docs/concepts/data_export.md @@ -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. diff --git a/docs/docs/settings/import.md b/docs/docs/concepts/data_import.md similarity index 93% rename from docs/docs/settings/import.md rename to docs/docs/concepts/data_import.md index 2fbdb7e37d..16b1e1f259 100644 --- a/docs/docs/settings/import.md +++ b/docs/docs/concepts/data_import.md @@ -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. diff --git a/docs/docs/manufacturing/bom.md b/docs/docs/manufacturing/bom.md index ebd29053b3..7e82cb68a5 100644 --- a/docs/docs/manufacturing/bom.md +++ b/docs/docs/manufacturing/bom.md @@ -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. diff --git a/docs/docs/part/create.md b/docs/docs/part/create.md index 9aaa06e55e..842e2133e5 100644 --- a/docs/docs/part/create.md +++ b/docs/docs/part/create.md @@ -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 diff --git a/docs/docs/part/index.md b/docs/docs/part/index.md index ec7f2fa282..1c7d048268 100644 --- a/docs/docs/part/index.md +++ b/docs/docs/part/index.md @@ -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. diff --git a/docs/docs/settings/export.md b/docs/docs/settings/export.md deleted file mode 100644 index 4ab560454a..0000000000 --- a/docs/docs/settings/export.md +++ /dev/null @@ -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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e477632584..ca0bb711ff 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -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