attach_document

Some records are built around an incoming file: an expense around its receipt, a claim around its evidence. attach_document is the small view widget behind that pattern, a button that opens the native file picker, uploads the chosen files as attachments of the current record, and optionally hands them to a Python method for processing.

Because it is a view widget, it appears as a <widget> element and stores nothing itself. Its three attributes cover the label, the styling and the follow-up call, and everything else, the save-first rule, the multi-file upload, the size check, is fixed behavior read from the source.

The widget's value is workflow compression. On expenses, one click covers what used to be four steps: save the draft, open the chatter, upload the receipt, then trigger digitization. The action attribute is the hinge; core points it at the expense method that runs OCR over the new attachments and fills amounts and dates from the receipt, and the automatic reload means the user watches the form populate itself.

The same pattern fits any document-first process you build: proof-of-delivery on field service tasks, signed contracts on subscriptions, certificates on quality checks. Wherever a scanned file should immediately drive record data, this button plus one model method is the shortest path.

The expense pattern, verbatim from core

<widget name="attach_document" string="Attach Receipt"
        action="attach_document" highlight="1"
        invisible="nb_attachment >= 1"/>

Highlighted while the expense has no receipt yet; a second, non-highlighted copy shows once attachments exist. The action value is a method name on the current model.

A minimal upload button, no follow-up

<widget name="attach_document" string="Upload Evidence"/>

Files land in the record's attachments and nothing else happens.

The Python side of an action

def attach_document(self, attachment_ids=None):
    # called once per click, after upload; record reloads afterward
    for attachment in self.env['ir.attachment'].browse(attachment_ids):
        ...

The upload path is worth reading once because it explains every edge case. The widget builds its own hidden file input with multiple enabled and accept="*", so there is no way in 19 to restrict file types from XML. On change, it loops the selection through checkFileSize, and a single file over the server limit aborts the entire batch with a notification, nothing partial uploads. The files then post to /web/binary/upload_attachment with the record's model and id, which is why the record must exist first and why beforeOpen forces the save.

Only after a successful upload does the optional action run, as an ORM call on the current record with attachment_ids passed as a keyword argument, followed by record.load(). Errors from the action surface as normal Odoo dialogs, and the attachments remain, they were created before the action ran. If your method should be transactional with the upload, it has to clean up the attachments itself.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. We read the widget's file on the public development branch at the time of writing; the branch is unstable and this page will be re-verified after release.

The development branch gives the widget its first real option: accepted_file_extensions, read from the options dictionary and applied to the hidden input's accept attribute, so the file picker itself filters types. The rest is the Owl typed-props migration, invisible from XML.