Reference Patterns

Reference Patterns

InvenTree contains a number of data models which require a unique reference field (such as Purchase Orders). 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).

Model Type	Default Pattern	Example Output
Purchase Order	PO-{ref:04d}	PO-0001
Sales Order	SO-{ref:04d}	SO-0123
Build Order	BO-{ref:04d}	BO-1234
Return Order	RMA-{ref:04d}	RMA-0987

Pattern Requirements

Patterns can contain a mixture of literal strings, named variable blocks, and wildcard characters:

• The pattern must contain a single {ref} 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
{ref}	Incrementing portion of the reference (*required)). Determines which part of the reference field auto-increments
{date}	The current date / time. This is a Python datetime object

The reference field pattern uses Python string formatting for value substitution.

Date Formatting

The {date} variable can be formatted using the Python Format Codes.

Substitution Examples

Some examples below demonstrate how the variable substitution can be implemented:

Pattern	Description	Example Output
PO-{ref}	Render the reference variable without any custom formatting	PO-123
PO-{ref:05d}	Render the reference variable as a 5-digit decimal number	PO-00123
PO-{ref:05d}-{date:%Y-%m-%d}	Render the date variable in isoformat	PO-00123-2023-01-17