source: main/trunk/docs/en/admin/references.rst @ 2073

Revision 2073, 5.1 KB checked in by pcosquer, 6 years ago (diff)

docs: admin: "how to customize generated references"

References -- how to customize generated references

System Message: ERROR/3 (<string>, line 5)

Unknown directive type "versionadded".

.. versionadded:: 1.3

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.

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.

How to customize it

It is possible to customize how references are generated by editing the file :file:``.

System Message: ERROR/3 (<string>, line 39); backlink

Unknown interpreted text role "file".

You need to add one variable: REFERENCE_PATTERNS.

By default, it is set to:

    "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

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:

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)

a :class:`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.

System Message: ERROR/3 (<string>, line 83); backlink

Unknown interpreted text role "class".

a :class:`.User` who will creates the object.

System Message: ERROR/3 (<string>, line 88); backlink

Unknown interpreted text role "class".
  • {user.username}: user's username.
  • {user.first_name}: user's first name
  • {user.last_name}: user's last name
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.

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.


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

Reference numbers shared between parts and documents


    "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.


    "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.

Including the date of creation

    "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.

Including user attributes

    "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.

Note: See TracBrowser for help on using the repository browser.