[feat] Support engineering CAD attachments for parts, assemblies and products

[buzzy84]

Problem / motivation

OpenMES currently supports images, PDFs, and selected media or document attachments, mainly in the context of process instructions and production steps.

For use in discrete manufacturing, engineering files must also be associated directly with:

• individual materials and parts;
• product types;
• product revisions;
• subassemblies;
• complete assemblies;
• process templates;
• individual process steps.

The initial supported engineering formats should include:

• STEP: .step, .stp;

• IGES: .iges, .igs;

• eDrawings native files:

  • .eprt;
  • .easm;
  • .edrw;

• externally generated HTML viewing packages;

• PDF and existing image formats.

Operators must be able to download authorized native engineering files.

For complete assemblies, operators should also be able to inspect an interactive browser-based representation directly from the OpenMES web interface, without requiring a native CAD application on every operator terminal.

The browser-based representation should be generated externally and uploaded to OpenMES as a self-contained HTML file or ZIP-based HTML package.

Released work orders must retain the exact engineering-document revision used when the work order was released. Uploading a newer document revision must not alter released or historical work orders.

Existing image, PDF, and process-step attachment behavior must remain compatible.

Proposed solution

Extend the current attachment and document model so that engineering documents can be associated with:

• a material or individual part;
• a product type;
• a product revision;
• a subassembly;
• a complete assembly;

Each engineering document should store (TBC):

• original filename;
• package type;
• document type;
• MIME type;
• compressed file size;
• extracted size, when applicable;
• entry-point filename, when applicable;
• document revision;
• checksum;
• upload timestamp;
• uploaded-by user;
• lifecycle status;
• optional validity or effectivity dates;
• related entity type and entity identifier.

Suggested package types:

native_cad
neutral_cad
edrawings_native
interactive_html
pdf
image

Suggested lifecycle states:

draft
released
obsolete

Files must be uploadable, downloadable, and listable through both the OpenMES user interface and authenticated REST API endpoints.

Suggested endpoints:

POST /api/v1/engineering-documents
GET /api/v1/engineering-documents
GET /api/v1/engineering-documents/{document}
GET /api/v1/engineering-documents/{document}/download
GET /api/v1/engineering-documents/{document}/view/{path}
POST /api/v1/engineering-documents/{document}/release
POST /api/v1/engineering-documents/{document}/obsolete

The binary file and its metadata may be uploaded using multipart/form-data.

Example metadata:

{
  "entity_type": "product_revision",
  "entity_id": 42,
  "package_type": "interactive_html",
  "document_type": "assembly_model",
  "revision": "B",
  "lifecycle_status": "released",
  "entry_point": "index.html"
}

Native CAD files must remain downloadable when the authenticated user has the required authorization.

Formats that cannot be previewed in the browser must remain available for download and opening with an appropriate desktop viewer.

PDF and image preview behavior must remain unchanged.

An interactive HTML representation may be uploaded as:

• a single self-contained .html file (or equivalent) as exported from the CAD

  • an entry-point HTML file;
  • JavaScript assets;
  • CSS assets;
  • geometry or model data;
  • textures;
  • other supporting resources.

Example package:

ASSEMBLY-1000-REV-B.zip
├── index.html
├── viewer.js
├── viewer.css
├── model/
│   ├── assembly-data.bin
│   └── assembly-metadata.json
└── assets/
    └── toolbar-icons.svg

The operator interface should render an interactive package through a dedicated viewer component using a sandboxed <iframe>.

Conceptual example:

<iframe
  src="/api/v1/engineering-documents/123/view/index.html"
  sandbox="allow-scripts allow-same-origin"
  referrerpolicy="no-referrer"
  allow="fullscreen"
  loading="lazy"
  title="ASSEMBLY-1000 revision B">
</iframe>

The exact sandbox permissions must be minimized according to the requirements of the uploaded viewer.

The viewer should not receive access to:

• the camera;
• the microphone;
• geolocation;
• the clipboard;
• pop-up windows;
• top-level navigation;
• form submission;

unless a specific and documented viewer implementation requires a permission.

Uploaded HTML must never be inserted directly into the OpenMES application DOM using innerHTML or an equivalent unsanitized rendering mechanism.

Because an HTML package may contain executable JavaScript, it must be treated as active content rather than as a normal attachment.

The implementation must include:

• authenticated access;
• entity-level authorization;
• document-specific isolated paths;
• strict archive validation;
• configurable upload and extraction limits;
• extension and MIME-type allowlists;
• audit logging;
• immutable released revisions;
• restrictive response headers;
• X-Content-Type-Options: nosniff;
• non-public and non-predictable storage paths;
• prevention of access to OpenMES authentication cookies;
• prevention of access to arbitrary OpenMES application APIs.

Interactive packages should preferably be served from a dedicated origin or subdomain.

Example:

OpenMES application:
https://mes.example.com

Engineering viewer content:
https://viewer.mes.example.com

Where a separate origin is not available, the implementation should use:

• sandboxed iframes;
• document-scoped signed URLs;
• short-lived access URLs;
• a dedicated route group;
• restrictive response headers.

Viewer responses should define a restrictive Content Security Policy.

A baseline policy could be:

default-src 'none';
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;
font-src 'self' data:;
connect-src 'self';
worker-src 'self' blob:;
media-src 'self' blob:;
object-src 'none';
frame-ancestors https://mes.example.com;
base-uri 'none';
form-action 'none';

The policy may be adjusted for a documented viewer implementation, but external network access must remain disabled by default.

References to third-party CDNs should be rejected or replaced with local package resources whenever possible.

By default, an embedded package must not be allowed to:

• load scripts from external domains;
• submit information to external services;
• access arbitrary OpenMES endpoints;
• retrieve other engineering documents;
• access local network resources.

Any required network destination must be explicitly allowlisted.

The same engineering-document revision may contain multiple representations.

Example:

ASSEMBLY-1000 revision B
├── native: ASSEMBLY-1000-B.easm
├── neutral: ASSEMBLY-1000-B.step
├── interactive: ASSEMBLY-1000-B-viewer.zip
└── drawing: ASSEMBLY-1000-B.pdf

The interactive HTML representation must not be the only retained copy of the engineering document.

If an interactive package cannot be rendered:

• OpenMES must show a clear error;
• authorized native or neutral files must remain downloadable;
• PDF and image representations must remain accessible.

When a work order is released, OpenMES must retain a reference to the exact engineering-document revision active at that time.

The snapshot should retain at least:

• engineering document ID;
• document revision;
• selected representation;
• checksum;
• lifecycle status at release;
• release timestamp.

Example:

Work order: WO-2026-0042
Product: ASSEMBLY-1000
Product revision: B
Engineering document: ASSEMBLY-1000-REV-B
Document checksum: sha256:...

If revision C is uploaded later, work order WO-2026-0042 must continue to reference revision B.

Released document revisions must be immutable. Obsolete revisions must remain available for historical traceability.

From the work-order or process-step screen, the operator should be able to:

• open the interactive assembly viewer;
• switch the viewer to full-screen mode;
• download authorized engineering files;
• see the product code and revision;
• see the document revision and lifecycle status;
• see when the document was released;
• return easily to the current production step.

Where supported by the uploaded viewer, the interactive representation may provide:

• rotation;
• pan;
• zoom;
• fit to screen;
• component selection;
• component visibility controls;
• exploded assembly views;
• component-name inspection;
• predefined views.

These capabilities belong to the uploaded viewer package and do not need to be reimplemented by OpenMES.

Affected roles

• Operator
• Supervisor
• Admin

Alternatives considered

Storing only native .easm, .eprt, or .edrw files was considered.

This would preserve the original files but would require compatible desktop software on every operator terminal. Native files should remain supported as download options, but this approach alone does not satisfy the browser-based shop-floor use case.

Storing only an external link to an engineering viewer was also considered.

This would introduce dependencies on:

• external service availability;
• network connectivity;
• external user licenses;
• separate authorization systems;
• continued availability of historical revisions.

The preferred approach is for the browser-viewable HTML representation to be generated before upload to OpenMES.

Developing a complete WebGL CAD viewer inside OpenMES was considered out of scope for the initial implementation.

OpenMES should provide:

• secure storage;
• document associations;
• revision management;
• authorization;
• secure delivery;
• iframe embedding;
• auditability.

The uploaded package should provide the actual model-rendering implementation.

Additional context

Suggested document structure:

Product revision: ASSEMBLY-1000 / B
├── Assembly viewer
│   └── ASSEMBLY-1000-B-viewer.zip
├── Native eDrawings
│   └── ASSEMBLY-1000-B.easm
├── Neutral CAD
│   └── ASSEMBLY-1000-B.step
└── Drawing
    └── ASSEMBLY-1000-B.pdf

Suggested operator interface:

┌──────────────────────────────────────────────────────────┐
│ ASSEMBLY-1000 — Revision B — Released                   │
├──────────────────────────────────────────────────────────┤
│                                                          │
│               Embedded interactive viewer                │
│                                                          │
│       Rotate | Pan | Zoom | Explode | Full screen        │
│                                                          │
├──────────────────────────────────────────────────────────┤
│ Released: 2026-07-10                                     │
│ [Download EASM] [Download STEP] [Open PDF drawing]       │
└──────────────────────────────────────────────────────────┘

The HTML package should be generated and validated before it is uploaded to OpenMES.

OpenMES must not execute arbitrary uploaded HTML without sandboxing, archive validation, access control, restrictive response headers, and security isolation.