Prerequisites

Before configuring the editor, make sure that:

• The bb_document_control module is installed and upgraded in Odoo.
• ONLYOFFICE Docs is available from a public or private URL reachable by users' browsers.
• ONLYOFFICE can reach the public Odoo URL.
• You have the Document Control Manager or Administrator group.
• Users who need to edit controlled documents have the Document Controller or Manager group.

Open Document Editor Settings

Go to:

Document Control > Configuration > Settings > Document Editor Settings

The settings wizard stores values in Odoo system parameters.

Configure Editor Provider

Set the following fields:

After entering the values, click Save.

Configure Odoo Public URL for ONLYOFFICE

ONLYOFFICE must be able to download files from Odoo and send save callbacks back to Odoo. If the Odoo web.base.url is internal, uses localhost, or uses a port that is not reachable from ONLYOFFICE, set this system parameter manually:

bb_document_control.ims_onlyoffice_odoo_public_url = https://odoo.example.com

Path:

Settings > Technical > Parameters > System Parameters

Use the URL that ONLYOFFICE can reach from its server or container.

Supported File Behavior

If ONLYOFFICE is not configured, Office files show an unsupported preview message and users should download the file instead.

File Buttons

Open a document and go to the Files / Online Documents tab.

Common buttons are:

• View - opens a preview or ONLYOFFICE viewer.
• Download - downloads the original file.
• Edit - opens ONLYOFFICE in edit mode if the file type is supported.
• Set Primary - marks the file as the main document file.
• New Version - copies the file into a new file version.

Editing Controlled Documents

Approved and effective documents are protected.

When Force New Revision on Controlled Edit is enabled:

1. A Document Controller or Manager clicks Edit.
2. The module creates a draft revision copy.
3. The original controlled file remains unchanged.
4. The document returns to draft revision status for the next review and approval cycle.

When this option is disabled, approved and effective files cannot be edited directly.

File Locks

The file model supports locking:

• Lock prevents other users from editing the file.
• Unlock releases the file.
• Managers can unlock files locked by another user.

Use locking when more than one controller may edit the same source document.

Save Callback

ONLYOFFICE saves edited files back to:

/ims/document/file/<file_id>/onlyoffice/callback

The module validates:

• The database context.
• The callback access token.
• The JWT signature when a JWT secret is configured.

If saves do not return to Odoo, check that ONLYOFFICE can reach the Odoo public URL and that the JWT secret matches.

Recommended Test

1. Open Document Control > Documents & Records > Documents > All Documents.
2. Create a draft document or open an existing draft document.
3. Add a .docx file on the Files / Online Documents tab.
4. Click View.
5. Confirm that the file opens in ONLYOFFICE.
6. Click Edit.
7. Make a small change.
8. Close the editor and wait for ONLYOFFICE to save.
9. Reopen the file and confirm that the content changed.
10. Check the file Activity Log for view, edit open, and edit save entries.

System Parameters Used by the Module

Related Guides

• ONLYOFFICE_SERVER_SETUP.md
• TROUBLESHOOTING.md

What ONLYOFFICE Does

The module uses ONLYOFFICE Docs to preview and edit Office files in the browser.

The integration flow is:

1. An Odoo user clicks View or Edit on a document file.
2. Odoo opens /ims/document/file/<file_id>/viewer or /ims/document/file/<file_id>/editor.
3. The browser loads the ONLYOFFICE Docs JavaScript API from the configured ONLYOFFICE server.
4. ONLYOFFICE fetches the file from Odoo using a signed URL.
5. When the user saves, ONLYOFFICE posts the edited file back to Odoo using the callback URL.

Because of this, the ONLYOFFICE server must be able to reach the public Odoo URL.

Requirements

• A Linux server or VM for ONLYOFFICE Docs.
• Docker installed.
• At least 4 GB RAM and enough disk space for document cache and logs.
• A DNS name for ONLYOFFICE, for example docs.example.com.
• HTTPS certificate for production use.
• Network access from ONLYOFFICE Docs to the Odoo public URL.
• Network access from users' browsers to both Odoo and ONLYOFFICE.

Official references:

• ONLYOFFICE Docker installation
• ONLYOFFICE JWT configuration

Recommended Docker Run Command

Use a fixed JWT secret. ONLYOFFICE Docs 7.2 and later enables JWT by default and may generate a random secret if you do not provide one. A random regenerated secret can break integrations after container rebuilds or restarts.

docker run -d \
  --name onlyoffice-documentserver \
  --restart=always \
  -p 80:80 \
  -e JWT_ENABLED=true \
  -e JWT_SECRET='replace_with_a_long_random_secret' \
  -e JWT_HEADER='Authorization' \
  onlyoffice/documentserver

For HTTPS directly in the container:

docker run -d \
  --name onlyoffice-documentserver \
  --restart=always \
  -p 80:80 \
  -p 443:443 \
  -e LETS_ENCRYPT_DOMAIN='docs.example.com' \
  -e LETS_ENCRYPT_MAIL='admin@example.com' \
  -e JWT_ENABLED=true \
  -e JWT_SECRET='replace_with_a_long_random_secret' \
  -e JWT_HEADER='Authorization' \
  onlyoffice/documentserver

Recommended Docker Compose

services:
  onlyoffice-documentserver:
    image: onlyoffice/documentserver:latest
    container_name: onlyoffice-documentserver
    restart: always
    ports:
      - "80:80"
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: "replace_with_a_long_random_secret"
      JWT_HEADER: "Authorization"
    volumes:
      - onlyoffice_logs:/var/log/onlyoffice
      - onlyoffice_data:/var/www/onlyoffice/Data
      - onlyoffice_lib:/var/lib/onlyoffice

volumes:
  onlyoffice_logs:
  onlyoffice_data:
  onlyoffice_lib:

If you use a reverse proxy such as Nginx, put HTTPS on the public proxy and forward traffic to the ONLYOFFICE container.

Reverse Proxy Checklist

Use this checklist when https://docs.example.com is handled by Nginx, Apache, Cloudflare, or another proxy.

• WebSocket upgrade headers are allowed.
• Large request bodies are allowed for Office files.
• Proxy timeout is long enough for file conversion and save callbacks.
• HTTPS certificate is valid and trusted by browsers.
• The public URL opens the ONLYOFFICE welcome page.
• The Odoo server and user browsers can reach the same ONLYOFFICE URL.

Example Nginx notes:

client_max_body_size 200m;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Verify ONLYOFFICE

Open this URL in a browser:

https://docs.example.com

You should see the ONLYOFFICE Docs welcome page.

Then check logs if needed:

docker logs onlyoffice-documentserver --tail 100

Network Rules

The integration needs traffic in the following directions:

Do not use localhost as the Odoo URL unless ONLYOFFICE runs in the same network namespace as Odoo. In most deployments, localhost from inside the ONLYOFFICE container means the ONLYOFFICE container itself, not the Odoo server.

Security Recommendations

• Use HTTPS for both Odoo and ONLYOFFICE.
• Keep JWT enabled.
• Use a long random JWT secret.
• Store the same JWT secret in Odoo Document Editor Settings.
• Restrict the ONLYOFFICE server firewall to trusted traffic where possible.
• Keep ONLYOFFICE Docs updated.
• Back up the volumes for logs, data, and cache if you need operational traceability.

Odoo-Specific Notes

The module generates ONLYOFFICE URLs like:

/ims/document/file/<file_id>/content?db=<database>&access_token=<token>&download=0
/ims/document/file/<file_id>/onlyoffice/callback?db=<database>&access_token=<token>

The db query parameter is important on multi-database Odoo hosts.

If ONLYOFFICE cannot reach Odoo, set this Odoo system parameter:

bb_document_control.ims_onlyoffice_odoo_public_url = https://odoo.example.com

Set it under Settings > Technical > Parameters > System Parameters in developer mode.

Next Step

After ONLYOFFICE is running, configure Odoo using:

bb_document_control/docs/ODOO_DOCUMENT_EDITOR_SETUP.md