8. References – how to customize generated references

New in version 1.3.

8.1. Reference numbers

Parts and documents have a reference which is a short text field. The reference is shared between two revisions of a part or document. Generally, a reference includes a number that increases by one after each creation.

OpenPLM extracts this number and stores it in the database. When a new object is created, OpenPLM suggests a reference generated with the maximum stored reference number.

The maximum reference number is not equal to the count of objects since two revisions shared the same number.

8.2. Default behavior

By default, OpenPLM generates distinct references for parts and documents.

For parts, it generates the following references: PART_00001, PART_00002, ..., PART_00050, PART_155555.

For documents, it generates the following references: DOC_00001, DOC_00002, ..., DOC_00050, DOC_155555.

Parts and documents have two distinct counters.

8.3. How to customize it

It is possible to customize how references are generated by editing the file settings.py.

You need to add one variable: REFERENCE_PATTERNS.

By default, it is set to:

REFERENCE_PATTERNS = {
    "shared": False,
    "part": (u"PART_{number:05d}", r"^PART_(\d+)$"),
    "doc": (u"DOC_{number:05d}", r"^DOC_(\d+)$"),
}

As you can see, it is a python dictionary with three keys (all keys are required).

shared is a boolean. If set to True, parts and documents shared the same counter.

part and document describe how reference are generated and how number are extracted. Their values are a tuple with two strings:

• the first string is a format template string
• the second string is a regular expression pattern

8.3.1. Format template string

The format template string should be a unicode object (u""). It must be a standard python format expression.

When the reference is generated, the template is formatting with the following parameters:

number

the computed reference number. Obviously, it must be present in the template. You can add padding, for example {number:05d} adds up to 5 zeros before the number (00001, 00145, 78954, 12454558)

now

a datetime.datetime object representing the current date. You can specify a special format to put the current year, month, day, etc. See the strftime documentation for all possibilities.

user

a User who will creates the object. You should not write directly {user}, you should append one of its attributes:

• {user.username}: username (login).
• {user.first_name}: first name
• {user.last_name}: last name

initials

initials of the user

Be careful when you add a username, first name or last name since the generated reference may contains forbidden characters and be too long.

8.3.2. Regular expression pattern

OpenPLM must known how to extract. A regular expression pattern must be given. It must contain one pair of parenthesis that will matches a number ((\d+)).

OpenPLM accepts a compiled pattern if you need to set a special flag to the regular expression.

8.4. Examples

In all examples, a document, a part, another part and a document (in that order) are created.

8.4.1. Reference numbers shared between parts and documents

8.4.1.1. PART_XX and DOC_XX

settings.py:

REFERENCE_PATTERNS = {
    "shared": True,
    "part": (u"PART_{number:05d}", r"^PART_(\d+)$"),
    "doc": (u"DOC_{number:05d}", r"^DOC_(\d+)$"),
}

will generate sequences like DOC_00001, PART_00002, PART_00003, DOC_00004, etc.

8.4.1.2. OBJ_XX

settings.py:

REFERENCE_PATTERNS = {
    "shared": True,
    "part": (u"OBJ_{number:05d}", r"^OBJ_(\d+)$"),
    "doc": (u"OBJ_{number:05d}", r"^OBJ_(\d+)$"),
}

will generate sequences like OBJ_00001, OBJ_00002, OBJ_00003, OBJ_00004, etc.

8.4.2. Including the date of creation

settings.py:

REFERENCE_PATTERNS = {
    "shared": False,
    "part": ("{now:%Y}-{number}-part", r'^\d{4}-(\d+)-part$'),
    "doc": ("{now:%y}-{number}-doc", r'^\d\d-(\d+)-doc$'),
}

will generate sequences like 13-1-doc, 2013-1-part, 2013-2-part, and 13-2-doc, etc.

8.4.3. Including user attributes

settings.py:

REFERENCE_PATTERNS = {
    "shared": False,
    "part": ("{user:username}-{number}-part", r'^.*-(\d+)-part$'),
    "doc": ("{initials}-{number}-doc", r'^.*-(\d+)-doc$'),
}

If the user is Robert Baratheon <rbaratheon>, it will generate sequences like RB-1-doc, rbaratheon-1-part, rbaratheon-2-part, and RB-2-doc, etc.