Skip to content

File Folder Rules

These rules define how calServer stores, versions, releases, and assigns files in an audit-proof way. They apply equally to every upload path — the inbox folder, the central document management, or a direct upload on a record (e.g. the inventory detail page).

The Seven Rules

  1. One folder = one document category. Each document category (e.g. inventory_doc, certificate) is configured in the file management with its own inbox folder and its own matching pattern.

  2. Pattern without {#ANY#} = exactly one document per record. Example {asset_number}: the file is automatically renamed to the pattern on upload. Uploading again creates a new minor version (draft) of the same version chain — never a copy.

  3. Pattern with {#ANY#} = multiple documents per record. Example {asset_number}_{#ANY#}: the pattern part is enforced, the free part comes from the filename (INV-0042_Manual, INV-0042_Certificate, …). Each unique name forms its own version chain; same name = new version, new name = new document.

  4. {#IGNORE#} forces versioning. A pattern containing {#IGNORE#} creates a new version on every re-upload, regardless of the filename.

  5. Reading in folders remains the central everyday path. Files in the inbox folder are assigned by filename↔pattern matching: a unique match is linked automatically, multiple matches import without a direct link, no match ends up as "unmatched" with a reason and rename-to-fix. Even without a direct link the document appears on every matching record (name-based pattern matching as in V1) — e.g. a type photo Manufacturer_Model_Front.jpg on all identical devices.

  6. Release workflow. Uploads are drafts (minor version). Releasing creates a new major version; unreleased versions are only visible to the roles and groups configured on the document category.

  7. Complete processing trail. Every upload — including direct uploads on a record — leaves an inbox trail entry (status, checksum, processed by/at, resulting document). Source files are archived, never silently deleted; imported trail entries cannot be removed.

Placeholder notations

Patterns accept API field names ({asset_number}) and V1 field codes ({I4201}) interchangeably — including fields taken over by the V1 migration. Both are aliases of the same field.

Uploads in the Application

When a file is uploaded directly on a record (e.g. document category inventory_doc on an inventory item), the same rules apply:

  • The file is automatically named after the category's pattern (rule 2 or 3).
  • Without a record context (central upload with a category), the filename must match the pattern; a unique match links the document automatically.
  • The upload appears in the inbox processing trail (rule 7).

Factory Defaults on Fresh Installations

A fresh V2 installation creates three default document categories (only when the file management is empty; a V1 migration replaces them with the customer's configuration):

Category Inbox folder Pattern
inventory_img (default image folder) bilder {manufacturer}_{model}_{#ANY#}
inventory_doc dokumente {asset_number}_{#ANY#}
certificate zertifikate {certificate_number}

The image pattern follows the "display by manufacturer/model" rule: any number of images per device, and a type photo automatically appears on all devices with the same manufacturer/model combination.

System folders

A few folders belong to a process inside the program — they are not merely a factory default but the place where that process is configured. The file management labels them Systemordner (system folder).

System folder Grid Inbox folder Pattern
dcc (digital calibration certificate) Calibration dcc {certificate_number}

Three differences from a folder you create yourself:

  • It is created at installation and retro-fitted on existing systems with the next update. An existing row with the same column name is adopted, not overwritten — the configured folder name and pattern stay.
  • It cannot be deleted. Without it the process would lose its only configuration surface, and filing would fail with nothing anywhere to say why. To stop files going in, empty the folder or restrict it by role and group.
  • Everything else is free: folder name, pattern, roles, groups, sort order.

Why the DCC does not live in zertifikate

Both folders would match on the certificate number — and the version chain keys on document category and name. An ingested 12345.xml would therefore become the next version of the PDF certificate 12345.pdf: two different documents in one chain, with the older one dropping out of sight.

Enabling Automatic Processing

Cyclic processing of the inbox folder is disabled by default to avoid conflicts with a calServer V1 instance running in parallel. For V2-only installations:

DMS_INBOX_ENABLED=true

Details on processing and the status model: inbox folder.