195 lines
11 KiB
Markdown
195 lines
11 KiB
Markdown
---
|
|
title: Parameters
|
|
---
|
|
|
|
## Parameters
|
|
|
|
A *parameter* describes a particular "attribute" or "property" of a specific object in InvenTree. Parameters allow for flexible and customizable data to be stored against various InvenTree models.
|
|
|
|
!!! note "Business Logic"
|
|
Parameters are not used for any core business logic within InvenTree. They are intended to provide additional metadata for objects, which can be useful for documentation, filtering, or reporting purposes.
|
|
|
|
Parameters can be associated with various InvenTree models.
|
|
|
|
### Parameter Tab
|
|
|
|
Any model which supports parameters will have a "Parameters" tab on its detail page. This tab displays all parameters associated with that object:
|
|
|
|
{{ image("concepts/parameter-tab.png", "Parameters Example") }}
|
|
|
|
## Parameter Templates
|
|
|
|
Parameter templates are used to define the different types of parameters which are available for use. The following attributes are defined for a parameter template:
|
|
|
|
| Attribute | Description |
|
|
| --- | --- |
|
|
| Name | The name of the parameter template (*must be unique*) |
|
|
| Description | Optional description for the template |
|
|
| Units | Optional units field (*must be a valid [physical unit](#parameter-units)*) |
|
|
| Model Type | The InvenTree model to which this parameter template applies (e.g. Part, Company, etc). If this is left blank, the template can be used for any model type. |
|
|
| Choices | A comma-separated list of valid choices for parameter values linked to this template. |
|
|
| Checkbox | If set, parameters linked to this template can only be assigned values *true* or *false* |
|
|
| Selection List | If set, parameters linked to this template can only be assigned values from the linked [selection list](#selection-lists) |
|
|
| Unique | Enforce a [uniqueness requirement](#parameter-uniqueness) on parameter values linked to this template |
|
|
|
|
{{ image("concepts/parameter-template.png", "Parameters Template") }}
|
|
|
|
### Create Template
|
|
|
|
Parameter templates are created and edited via the [Admin Center](../settings/admin.md#admin-center).
|
|
|
|
To create a template:
|
|
|
|
- Navigate to the "Settings" page
|
|
- Click on the "Parameters" tab
|
|
- Click on the "New Parameter" button
|
|
- Fill out the `Create Parameter Template` form: `Name` (required) and `Units` (optional) fields
|
|
- Click on the "Submit" button.
|
|
|
|
An existing template can be edited by clicking on the "Edit" button associated with that template:
|
|
|
|
{{ image("part/parameter_template_edit.png", "Edit Parameter Template") }}
|
|
|
|
### Create Parameter
|
|
|
|
After [creating a template](#create-template) or using the existing templates, you can add parameters to any part.
|
|
|
|
To add a parameter, navigate to a specific part detail page, click on the "Parameters" tab then click on the "New Parameters" button, the `Create Parameter` form will be displayed:
|
|
|
|
{{ image("part/create_part_parameter.png", "Create Parameter Form") }}
|
|
|
|
Select the parameter `Template` you would like to use for this parameter, fill-out the `Data` field (value of this specific parameter) and click the "Submit" button.
|
|
|
|
### Parameter Uniqueness
|
|
|
|
A parameter template can be configured to enforce a uniqueness requirement on the values of any parameters linked to it. This is useful for parameters which are expected to act as a unique identifier and prevents duplicate values from being entered by mistake.
|
|
|
|
The `Unique` attribute on a parameter template supports the following options:
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| No uniqueness required | The default option - no restriction is placed on parameter values |
|
|
| Unique for model type | A parameter value must be unique amongst all other parameters (linked to this template) which are assigned to the *same* model type. For example, a template with this option enabled could be used to enforce unique serial numbers across all `Part` instances, without preventing the same value from also being used against a `Company` instance |
|
|
| Globally unique | A parameter value must be unique amongst *all* other parameters linked to this template, regardless of the model type to which they are assigned |
|
|
|
|
!!! info "Case Insensitive"
|
|
Uniqueness checks are case-insensitive - for example, the values `ABC123` and `abc123` are considered to be duplicates of each other.
|
|
|
|
If a parameter value is entered which does not satisfy the uniqueness requirement of its template, it will be rejected and an error message displayed.
|
|
|
|
#### Validation Against Numeric Value
|
|
|
|
If a parameter template defines a set of [units](#parameter-units), uniqueness is checked against the *normalized numeric value* of the parameter, rather than the raw text entered. This ensures that equivalent values expressed in different (but compatible) units are correctly detected as duplicates.
|
|
|
|
For example, if a *Resistance* template (with base units of `ohm`) enforces uniqueness, then a value of `1k` would be rejected as a duplicate of an existing value of `1000`, as they both represent the same physical quantity.
|
|
|
|
Templates which do not define a set of units are compared using a direct (case-insensitive) text comparison of the raw parameter value.
|
|
|
|
#### Copying Caveats
|
|
|
|
Some workflows in InvenTree allow parameters to be copied from one object to another - for example, when duplicating a part, build order, or other object which supports parameters.
|
|
|
|
Any parameter which is linked to a template with a uniqueness requirement is *skipped* when copying parameters in this way. This prevents the copy operation from creating a duplicate (and therefore invalid) value on the new object. If this occurs, the new object simply will not have a parameter created against that particular template - it can be added manually (with a distinct value) afterwards.
|
|
|
|
#### Category Parameter Caveats
|
|
|
|
A parameter template can be linked to a part category, along with a default value which is automatically applied to any new parts created within that category (or a sub-category).
|
|
|
|
This default value system is not compatible with a template which enforces a uniqueness requirement - applying the *same* default value to every part in a category would immediately conflict with the "unique" requirement, as soon as more than one part exists in that category.
|
|
|
|
For this reason, a category-based default value is *not* applied for any parameter template which has a uniqueness requirement configured. If you need to assign values for such parameters, this must be done manually (or via the API) on a per-part basis.
|
|
|
|
## Parametric Tables
|
|
|
|
Parametric tables gather all parameters from all objects of a particular type, to be sorted and filtered.
|
|
|
|
Tables views which support parametric filtering and sorting will have a "Parametric View" button above the table:
|
|
|
|
{{ image("concepts/parametric-parts.png", "Parametric Parts Table") }}
|
|
|
|
### Sorting by Parameter Value
|
|
|
|
The parametric parts table allows the returned parts to be sorted by particular parameter values. Click on the header of a particular parameter column to sort results by that parameter:
|
|
|
|
{{ image("part/part_sort_by_param.png", "Sort by Parameter") }}
|
|
|
|
### Filtering by Parameter Value
|
|
|
|
The parametric parts table allows the returned parts to be filtered by particular parameter values. Click on the {{ icon("filter") }} button associated with the particular parameter, and enter the value you wish to filter against:
|
|
|
|
{{ image("part/filter_by_param.png", "Filter by Parameter") }}
|
|
|
|
The available filter options depend on the type of parameter being filtered. For example, a parameter with a limited set of choices will allow you to filter by those choices, while a numeric parameter will allow you to filter against a specific value and operator (e.g. greater than, less than, etc.).
|
|
|
|
#### Filtering by Multiple Parameters
|
|
|
|
Multiple parameters can be used to filter the parametric table. Simply add a new filter for each parameter you wish to filter against. The results will be filtered to include only parts which match *all* of the specified filters.
|
|
|
|
Each parameter column indicates whether a filter is currently applied:
|
|
|
|
{{ image("part/multiple_param_filters.png", "Multiple Parameter Filters") }}
|
|
|
|
#### Multiple Filters Against the Same Parameter
|
|
|
|
It is possible to apply multiple filters against the same parameter. For example, you can filter for parts with a *Resistance* parameter greater than 10kΩ and less than 100kΩ by adding two filters for the *Resistance* parameter:
|
|
|
|
{{ image("part/multiple_filters_same_param.png", "Multiple Filters on Same Parameter") }}
|
|
|
|
#### Unit-Aware Filtering
|
|
|
|
When filtering against a parameter which has a unit defined, you can specify the value in any compatible unit. The system will automatically convert the value to the base unit defined for that parameter template.
|
|
|
|
For example, to show all parts with a *Resistance* parameter of greater than 10kΩ, you can enter `10k` or `10000` in the filter field, and the system will correctly interpret this as 10,000 ohms.
|
|
|
|
{{ image("part/filter_with_unit.png", "Unit Aware Filters") }}
|
|
|
|
#### Removing Filters
|
|
|
|
To remove a filter against a given parameter, click on the {{ icon("circle-x", color='red') }} button associated with that filter:
|
|
|
|
{{ image("part/remove_param_filter.png", "Remove Parameter Filter") }}
|
|
|
|
#### Available Filter Operators
|
|
|
|
The following filter operators are available for parameter filtering:
|
|
|
|
- `=`: Equal to
|
|
- `>`: Greater than
|
|
- `>=`: Greater than or equal to
|
|
- `<`: Less than
|
|
- `<=`: Less than or equal to
|
|
- `!=`: Not equal to
|
|
- `~`: Contains (for text parameters)
|
|
|
|
## Parameter Units
|
|
|
|
The *units* field (which is defined against a [parameter template](#parameter-templates)) defines the base unit of that template. Any parameters which are created against that unit *must* be specified in compatible units.
|
|
|
|
The in-built conversion functionality means that parameter values can be input in different dimensions - *as long as the dimension is compatible with the base template units*.
|
|
|
|
!!! info "Read Mode"
|
|
Read more about how InvenTree supports [physical units of measure](../concepts/units.md)
|
|
|
|
### Incompatible Units
|
|
|
|
If a parameter is created with a value which is incompatible with the units specified for the template, it will be rejected:
|
|
|
|
{{ image("part/part_invalid_units.png", "Invalid Parameter Units") }}
|
|
|
|
This behaviour can be disabled if required, so that any parameter value is accepted.
|
|
|
|
### Parameter Unit Sorting
|
|
|
|
Parameter sorting takes unit conversion into account, meaning that values provided in different (but compatible) units are sorted correctly:
|
|
|
|
{{ image("part/part_sorting_units.png", "Sort by Parameter Units") }}
|
|
|
|
### Selection Lists
|
|
|
|
Selection Lists can be used to add a large number of predefined values to a parameter template. This can be useful for parameters which must be selected from a large predefined list of values (e.g. a list of standardized color codes). Choices on templates are limited to 5000 characters, selection lists can be used to overcome this limitation.
|
|
|
|
It is possible that plugins lock selection lists to ensure a known state.
|
|
|
|
|
|
Administration of lists can be done through the `Parameter` section in the [Admin Center](../settings/admin.md#admin-center) or via the API.
|