Everjust Documents

EVERJUST Documents — Agent Skill

Operate the everjust.app Documents app as a running agent: browse a tenant's folders, create/move/upload/download files, tag and archive them, and understand where the bytes physically live. You reach the ORM through the platform's Odoo MCP (open an env against the right tenant DB, then search / read / create / write / call a method) — see [[everjust-agent-mcp]] for opening the session and [[everjust-platform]] for the invariants (one-DB-per-tenant, sudo/ACL boundaries, Odoo-19 API surface).

The addons are three OCA modules — dms (Document Management System: dms.file / dms.directory / dms.storage), fs_storage (generic fsspec storage backend: fs.storage), fs_attachment (routes ir.attachment bytes to an fs.storage) — plus one bespoke EVERJUST glue module, everjust_documents, that wires all three at Nextcloud over WebDAV. Custom source: <ww.everjust.app>/addons/everjust_documents/.

When to use this skill

• Browse / read a tenant's documents — list root storages, folders, files; fetch a file's bytes; read tags, size, checksum, lock state.
• Create / upload — make a folder (dms.directory) or a file (dms.file, content is base64), place a file into a directory.
• Organize — move a file to another directory, archive (soft-delete), lock/unlock, tag/categorize, rename.
• Storage / cloud plumbing — inspect or configure where files physically land (database / filestore / attachment→Nextcloud-over-WebDAV), test the private-cloud connection, point Documents at the cloud, migrate existing files to the current save type.

Do NOT use this skill for, and stop if the task is really:

• Odoo Enterprise "Documents" (documents.document, documents.folder, workspaces/workflow rules) — that model does not exist on this platform. This is the OCA dms product. Don't reach for documents.*.
• Raw ir.attachment juggling for chatter/reports/binary fields — that's generic Odoo, not this app. (fs_attachment does re-route attachment bytes, but you drive it through dms.file, not by hand-writing attachments.)
• Provisioning the Nextcloud tenant/account (creating the service user, app password, WebDAV root) — that's control-plane / infra work; this skill assumes the Nextcloud identity exists and only reads/sets the per-tenant connection params.
• DNS/registrar or mail — see [[everjust-mail-ops]] for the mail stack.

Is it even installed here? Check first

everjust_documents (+ fs_storage/fs_attachment) is installed on only some tenants. Verified 2026-07: installed on tcstartupweek and headsup; NOT on connectdomain (there dms is present as a transitive dependency but the WebDAV layer and app are uninstalled). The base dms module is broadly installed, but without everjust_documents there is no cloud storage and no "Cloud Files" launcher. Before any file operation, confirm:

env["ir.module.module"].sudo().search_read(
    [("name", "in", ["everjust_documents", "dms", "fs_storage", "fs_attachment"])],
    ["name", "state"])
# state == "installed" for all four ⇒ full cloud-backed Documents.
# Only "dms" installed ⇒ plain DMS (files in DB/filestore), no Nextcloud.

Architecture — where a file actually lives

Everything is per-company_id (tenant). The model layering, bottom-up:

The everjust wiring (why files land in Nextcloud): everjust_documents flips the tenant's dms.storage.save_type to attachment, so every dms.file becomes an ir.attachment; fs_attachment then routes new attachment bytes to the fs.storage flagged use_as_default_for_attachments=True; that storage is the webdav backend (code='everjust_nextcloud') pointing at the tenant's Nextcloud. Net effect: drop a file into Documents → it physically lands in Nextcloud over WebDAV, the DB keeps only metadata. No second tab, no sync cron — the cloud is the filestore. (res.config.settings adds the everjust_nc_* panel + the action_everjust_* buttons; per-tenant creds live in ir.config_parameter under everjust_documents.*, mirroring everjust_phone / everjust_ringover.)

Live state on tcstartupweek (illustrative): dms.storage "Default Storage" save_type=attachment; fs.storage id=1 code=everjust_nextcloud protocol=webdav use_as_default_for_attachments=True check=ls directory_path='tcstartupweek'; config params everjust_documents.nc_url=https://files.everjust.app/remote.php/dav/files/svc_tcstartupweek…, nc_user=svc_tcstartupweek, nc_password=***, nc_directory=tcstartupweek, files_url=https://files.everjust.app/apps/files.

Recipes

Route each through the Odoo MCP against the tenant DB (see [[everjust-agent-mcp]]).

Browse: storages → root folders → files

# Storage roots and their save_type (is this tenant cloud-backed?):
env["dms.storage"].search_read(
    [], ["name", "save_type", "inherit_access_from_parent_record", "root_directory_ids"])

# Root folders, then drill into one:
roots = env["dms.directory"].search_read(
    [("is_root_directory", "=", True)],
    ["name", "complete_name", "storage_id", "count_files", "count_directories"])
d = env["dms.directory"].search([("complete_name", "=", "Default Storage")], limit=1)
d.child_directory_ids.read(["name", "complete_name"])
env["dms.file"].search_read(
    [("directory_id", "=", d.id)],
    ["name", "mimetype", "human_size", "checksum", "tag_ids", "active"],
    order="name")

Create a folder (root vs child)

storage = env["dms.storage"].search([], limit=1)          # the tenant's storage
# ROOT folder — needs a storage; if storage.save_type == "attachment" it ALSO needs a model:
root = env["dms.directory"].create({
    "name": "Client Contracts",
    "is_root_directory": True,
    "storage_id": storage.id,
    # REQUIRED under attachment storage (constraint _check_storage_id_attachment_model_id):
    "model_id": env["ir.model"]._get("res.partner").id,   # or set res_model="res.partner"
})
# CHILD folder — inherits storage from parent; do NOT set storage_id:
sub = env["dms.directory"].create({"name": "2026", "parent_id": root.id})

A root directory MUST have a storage_id; a non-root MUST have a parent_id and inherits its storage (you cannot re-parent across storages — it raises UserError). Under save_type='attachment', a directory needs a model_id/res_model, and any non-root also needs res_id (it binds files to a business record).

Upload a file (content is base64)

import base64
data = base64.b64encode(open("/path/contract.pdf", "rb").read()).decode()
f = env["dms.file"].create({
    "name": "contract.pdf",           # unique within the directory (constraint)
    "directory_id": sub.id,
    "content": data,                  # base64 str; inverse writes it to the storage
})
f.read(["name", "mimetype", "extension", "human_size", "checksum", "save_type"])
# When the directory's storage is attachment-backed, create() auto-spawns an
# ir.attachment (f.attachment_id) whose bytes fs_attachment routes to Nextcloud.

Guardrails enforced on create/write: name must be valid + unique in the directory; extension not in dms.forbidden_extensions; size ≤ dms.binary_max_size MB (default 25). Write to content (base64) to replace bytes; never poke content_file/content_binary directly — those are the internal stores the content inverse manages.

Download a file's bytes

f = env["dms.file"].browse(file_id)
raw = base64.b64decode(f.content or b"")     # reads THROUGH the storage backend
open("/tmp/out.pdf", "wb").write(raw)
# For attachment-stored files you may also go via f.attachment_id.datas, but reading
# f.content is the storage-agnostic path and is what the app uses.

For an attachment-backed tenant this read hits Nextcloud over WebDAV live — it will raise if the cloud is unreachable (see Pitfalls), and it relies on the webdav4 patch.

Move, tag, archive, lock

# Move to another folder (same root storage only):
f.write({"directory_id": other_dir.id})
# Tag / categorize (tags are filtered by the file's category):
tag = env["dms.tag"].search([("name", "=", "Signed")], limit=1)
f.write({"category_id": cat.id, "tag_ids": [(6, 0, tag.ids)]})
# Archive (soft delete — hidden but kept; UNARCHIVE with active=True):
f.write({"active": False})
# Lock / unlock (prevents concurrent edits):
f.lock()      # sets locked_by = current user
f.unlock()

Configure / verify the private cloud (Nextcloud over WebDAV)

# 1) See the WebDAV backend and whether Documents is pointed at it:
env["fs.storage"].sudo().search_read(
    [("code", "=", "everjust_nextcloud")],
    ["protocol", "directory_path", "use_as_default_for_attachments", "check_connection_method"])
# 2) Test connectivity (idempotently ensures the fs.storage from config params, then ls root):
env["fs.storage"].sudo().test_everjust_nc_connection()      # True, or UserError with the reason
# 3) (Re)create the backend from the everjust_documents.* config params:
env["fs.storage"].sudo().ensure_everjust_nc_storage()       # looked up by code — idempotent
# 4) Point every dms.storage at the cloud (flip save_type→attachment; tests conn first):
env["res.config.settings"].create({}).action_everjust_point_documents_at_nc()

Per-tenant creds are in ir.config_parameter (everjust_documents.nc_url / nc_user / nc_password / nc_directory, plus files_url for the "Cloud Files" launcher). Set them via the Settings panel or by writing the params, then call ensure_everjust_nc_storage(). Never paste real cloud passwords into a tracked file, commit, PR, or log (see [[everjust-platform]]).

Migrate existing files to the current save type

# Files created BEFORE a save_type flip stay where they were. Relocate them:
storage = env["dms.storage"].search([], limit=1)
storage.action_storage_migrate()          # migrates files with require_migration=True
# Inspect what needs moving first:
env["dms.file"].search_read(
    [("require_migration", "=", True)], ["name", "migration", "save_type"])

Pitfalls (everjust-specific)

1. This is NOT Odoo Enterprise Documents. documents.document / documents.folder do not exist on this platform ('documents.document' in env is False). The models are dms.file / dms.directory / dms.storage. Don't write code against documents.*.

2. Files can physically live in Nextcloud — reads/writes need live connectivity. When dms.storage.save_type == 'attachment' and the default fs.storage is the webdav backend, a file's bytes are on Nextcloud, not in Postgres. Reading f.content (or f.attachment_id.datas) makes a live WebDAV round-trip; if Nextcloud is down / the app password rotated / the folder was moved, the read raises and the file appears "broken" even though its metadata row is fine. check_connection_method='ls' means the backend probes on every use and drops a stale connection from cache. Diagnose with env["fs.storage"].sudo().test_everjust_nc_connection() before assuming data loss.

3. The webdav4 monkeypatch is load-bearing. everjust_documents/models/webdav4_patch.py coerces WebdavFile.read(None) → read(-1); without it fsspec's "read everything" call raises TypeError and every attachment read from Nextcloud fails. It's applied at import and is idempotent. If reads fail with that TypeError, the module didn't load (wrong tenant / not installed / import error) — don't try to reimplement the read.

4. Attachment storage imposes hard constraints on folders. A directory on an attachment-backed storage MUST have a model_id/res_model (and a non-root also a res_id), and a dms.file there must resolve res_model+res_id — otherwise ValidationError. So you can't just make a free-floating folder on a cloud-backed tenant; bind it to a model/record. (On database/filestore storages this doesn't apply.)

5. You cannot change a directory's storage, and can't re-parent across storages. dms.directory.write raises UserError if a move would cross storages. Create in the right root, or migrate files explicitly (action_storage_migrate).

6. Only one fs.storage per company may be use_as_default_for_attachments. There's a constraint. Don't flip a second backend's flag on; use the everjust helper ensure_everjust_nc_storage() (keyed by code='everjust_nextcloud', idempotent) rather than hand-creating storages.

7. Write content (base64), never the raw stores. dms.file.content is a computed+inverse Binary that dispatches to content_file / content_binary / attachment_id per the storage save type. Writing content_binary/content_file yourself bypasses that and desyncs the file. Upload/replace bytes via content.

8. Flipping save_type does NOT move existing files. action_everjust_point_documents_at_nc only changes where new files go; old files keep their old storage until you run the per-storage migration. Don't assume a freshly-cloud-pointed tenant has its history in Nextcloud.

9. Everything is per-company_id/tenant. Storage, folders, files, DMS access groups, and the WebDAV creds are all tenant-scoped. Confirm you're on the right tenant DB and env.company before searching or creating (see [[everjust-agent-mcp]]). And confirm the app is actually installed on this tenant (the check above) — it is not universal (e.g. not on connectdomain).

10. DMS has its own permission layer. Access is governed by dms.access.group on directories (inherited down the tree), plus — under attachment storage with inherit_access_from_parent_record — the ACL of the linked business record. A sudo() search can see files an end user cannot; if you're acting as a user, respect permission_read/write/create/unlink on the records rather than sudo-ing around them.