mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-04-27 21:26:43 +00:00
1f2598b748
* Adds page documenting reference strings * Cleanup existing reference field documentation
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
---
|
|
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 |
|
|
|
|
### 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 |
|