A) Document Lifecycle & Revision Governance

Move from ad-hoc file shares to disciplined lifecycle management:

• States & workflow: Draft through review, approval, effectiveness, obsolescence, and archival—aligned to your authority matrix.
• Revisions: Maintain revision numbers, controlled file attachments, and history of what changed and who approved it.
• Ownership: Document owners, controllers, reviewers, and approvers with clear responsibilities.
• Review dates: Plan periodic review and next review triggers.
• Traceability: Link to standards, processes, sites, and departments for audit and KPI alignment.

B) Distribution, Acknowledgement & Controlled Copy Models

Ensure the right people receive the right version:

• Distribution lists: Target recipients by role, site, or department.
• Acknowledgements: Where policy requires read-and-confirm behaviour.
• Controlled vs uncontrolled: Reflect how your organization manages master copies versus informational copies.
• Evidence: Preserve who received what and when.

C) Records & Evidence Templates

Support the record half of “documented information” with clarity:

• Record templates: Standardize how evidence is captured for processes and audits.
• Controlled records: Align retention and access expectations with confidentiality levels.
• Operational linkage: Connect records to the processes and sites they evidence.

D) Integration & Executive Oversight

Document health is not an island:

• Issues & audits: Nonconformities and audit findings can reference the same document IDs.
• Risk & compliance: Obligations and controls map to the documentation that implements them.
• Management review: Feed document status, changes, and risks into review packs.

E) Multi-Site & Multi-Company Patterns

Scale governance without fragmenting the framework:

• Sites & entities: Scope documents and records to where they apply.
• Corporate groups: Align with Odoo company rules where separate legal entities need isolation.
• Consistent templates: Publish once; adapt locally only where permitted.

F) Multi-File Attachments & Online Document Editing

Go beyond a single binary attachment—manage a full document file portfolio with in-browser collaboration:

• Multiple files per document: Attach DOCX, XLSX, PPTX, PDF, and supporting files to one controlled document record with roles (editable source, controlled PDF, evidence, supporting, external).
• Bulk upload wizard: Import several files at once, assign a file role, and optionally mark the first file as primary.
• Per-file actions: View, Download, Edit, Set Primary, and New Version buttons on every file line—editor support is computed from file type and ONLYOFFICE configuration.
• ONLYOFFICE Docs integration: Configure server URL and JWT secret under IMS → Configuration → Document Control → Document Editor Settings. Preview and edit Office formats and PDFs directly in the browser.
• Controlled edit safety: Optional force-new-revision on approved/effective documents preserves the controlled copy while editing proceeds on a draft revision.
• Activity logging: Every view, download, edit, lock, and upload is recorded with user, timestamp, IP address, and details for audit evidence.
• Backward compatibility: Legacy main_file field is retained and synced with the primary file line.

Files / Online Documents tab — multi-file list with View, Download, Edit, Set Primary, and New Version actions.

Architecture at a Glance

1. Browser opens Odoo editor page and loads api.js from the ONLYOFFICE server via a standard <script src="..."> tag.
2. ONLYOFFICE downloads the file from /ims/document/file/<id>/content?access_token=...
3. User edits in the ONLYOFFICE iframe; on save ONLYOFFICE POSTs to /ims/document/file/<id>/onlyoffice/callback?access_token=...
4. Odoo validates JWT and callback token, stores the updated file, and writes an activity log entry.

1.1 Install ONLYOFFICE Document Server

Deploy ONLYOFFICE Docs on a dedicated host or VM. Common options:

• Docker (recommended): use the official ONLYOFFICE Document Server image and expose HTTPS on port 443.
• Linux package install: follow ONLYOFFICE installation guides for Ubuntu/Debian with Nginx as reverse proxy.
• Example hostname: https://office.bbtech.ae

Verify the API script is reachable:

curl -I https://office.bbtech.ae/web-apps/apps/api/documents/api.js

Expected response: HTTP 200 with Content-Type: application/javascript

1.2 Enable JWT (recommended for production)

Generate a strong shared secret and configure it on the ONLYOFFICE server. In local.json (Docker: inside the container or via mounted config):

{
  "services": {
    "CoAuthoring": {
      "secret": {
        "inbox": { "string": "YOUR_JWT_SECRET_HERE" },
        "outbox": { "string": "YOUR_JWT_SECRET_HERE" },
        "session": { "string": "YOUR_JWT_SECRET_HERE" }
      },
      "token": {
        "enable": {
          "request": { "inbox": true, "outbox": true },
          "browser": true
        }
      }
    }
  }
}

Restart ONLYOFFICE after changing JWT settings. Use the same secret in Odoo Document Editor Settings.

1.3 HTTPS and reverse proxy

Serve ONLYOFFICE over HTTPS with a valid certificate. Typical Nginx proxy headers:

• proxy_set_header Host $host;
• proxy_set_header X-Forwarded-Proto $scheme;
• proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Ensure the ONLYOFFICE container can make outbound HTTP/HTTPS requests to your Odoo public URL (see Part 2).

2.1 Public URL reachable by ONLYOFFICE

ONLYOFFICE downloads files and posts callbacks to absolute URLs built from your Odoo base URL. The Document Server must reach these endpoints — not localhost or an internal dev port.

• Set Settings → Technical → System Parameters → web.base.url to the public address users and ONLYOFFICE can reach.
• If Odoo runs on a non-standard port (e.g. :8019), place Nginx on port 80/443 and reverse-proxy to Odoo so external URLs omit the dev port.
• Example document URL passed to ONLYOFFICE:
  http://your-server/ims/document/file/1/content?access_token=...
• Example callback URL:
  http://your-server/ims/document/file/1/onlyoffice/callback?access_token=...

Optional: set system parameter bb_ims_document_control.ims_onlyoffice_odoo_public_url to override the base URL used for ONLYOFFICE document and callback links.

2.2 Firewall and routing

• Allow browsers to reach ONLYOFFICE HTTPS (port 443).
• Allow the ONLYOFFICE server outbound access to Odoo HTTP/HTTPS on the public URL.
• Odoo routes /ims/document/file/... are public with signed access tokens — no Odoo session cookie is required for ONLYOFFICE fetch/callback.

2.3 Install and upgrade the module

1. Install or upgrade IMS Document Control from Apps.
2. Restart the Odoo service after deployment.
3. Ensure the user has Document Control Administrator rights to access editor settings.

3.1 Open settings

Navigate to:

IMS → Configuration → Document Control → Document Editor Settings

3.2 Configure fields

Click Save. Settings are stored in ir.config_parameter under keys prefixed with bb_ims_document_control.ims_.

4.1 Pre-flight checks

1. Confirm curl -I https://office.bbtech.ae/web-apps/apps/api/documents/api.js returns 200.
2. In Odoo, open Settings → Technical → System Parameters and verify bb_ims_document_control.ims_editor_provider = onlyoffice.
3. From the ONLYOFFICE server, test that the Odoo public URL responds (file content route with a valid token).

4.2 Upload files and edit

1. Open a controlled document → Files / Online Documents tab.
2. Use Upload Multiple Files to attach DOCX, XLSX, PPTX, or PDF files.
3. On each file line, click View to preview or Edit to open ONLYOFFICE edit mode.
4. Supported editable formats: DOC, DOCX, ODT, RTF, TXT, XLS, XLSX, ODS, CSV, PPT, PPTX, ODP, and PDF (if enabled).
5. Check the file Activity Log tab for view, edit, and save events with user and IP details.

Troubleshooting

• “ONLYOFFICE API could not be loaded” — verify server URL, HTTPS certificate, and that api.js loads via a normal script tag (not fetch/XHR). Check browser console for blocked scripts.
• Editor opens but document is blank — ONLYOFFICE cannot reach Odoo file URL. Fix web.base.url, reverse proxy, or set ims_onlyoffice_odoo_public_url.
• Save does not persist — check callback URL reachability, JWT secret match, and Odoo server log for ONLYOFFICE callback errors.
• Edit button missing — confirm provider is onlyoffice, URL is set, and file extension is supported.

1. Dashboards

Document portfolio health and KPI-style visibility.

Secondary dashboard perspective.

2. Controlled documents

Documents register view.

Document form — detail and linkage.

Revision history and file governance.

3. Distribution

Distribution and acknowledgement context.

4. Records

Controlled records and templates.

Record templates.

5. Multi-File & Online Document Editing

Attach multiple files per document, configure ONLYOFFICE Docs, and preview or edit Office and PDF files in the browser—with full activity logging for audit evidence.

Document Editor Settings — configure ONLYOFFICE Docs as the online editor provider. Set server URL, JWT secret, force-new-revision behaviour, PDF editing, and maximum upload size.

Upload Multiple Files wizard — bulk-import attachments to a document. Choose a file role (editable source, controlled PDF, supporting, evidence, external) and optionally set the first file as primary.

Files / Online Documents tab — each file line shows extension, role, version, primary flag, and action buttons: View, Download, Edit, Set Primary, and New Version. Editor type is computed from file format and ONLYOFFICE configuration.

ONLYOFFICE view mode — open PDF and Office files in the browser with the full ONLYOFFICE toolbar. Header bar provides View, Edit Online, and Download shortcuts back to Odoo.

ONLYOFFICE edit mode — edit documents online with the native ONLYOFFICE ribbon (File, Home, Comment, Collaboration, View, Plugins, AI). Changes are saved back to Odoo via a secure callback.

File activity log — audit trail for every file action: view, download, edit open, lock, upload, and online editor sessions—with user, timestamp, IP address, and descriptive details.