File emailed documents and log what they say

Documents that matter arrive as email attachments and then sit in the mailbox, where nobody can find them again and nothing is written down. This keeps a register instead: every PDF arriving on mail that matches your search is copied into a Box folder and gets one row on your spreadsheet saying where it came from, where it now lives and what it says.

The row starts with six fixed columns - when it was filed, who sent it, the subject, the file name, a link to the filed copy, and whether the document could be read - and then one column for each field you list in 'documentFields', in the order you list them. Give your tab those headings.

Every value in those field columns comes out of the document itself. Nothing writes a supplier, a date, an amount or a document number that the reader did not find on the page: a field the document does not carry is left as an empty cell rather than filled in with something plausible, and the values are matched back to your column headings by name, so a column can never end up holding the field underneath it. If a document cannot be read at all it is still filed and still gets a row, with the field columns empty and the status column saying so - a document missing from the register is worse than one that needs a person to finish it.

Only PDF attachments are treated as documents. A sender's signature logo is an image a document reader will happily describe, and it has no business becoming a row of financial detail.

The order of the writes is deliberate: the copy goes into Box, the row goes onto the sheet, and only then is the mail labelled - and only if nothing on that message was left undone. If a run dies part way, or a copy will not upload, the mail keeps no label and the next run does the same work again: an extra copy in the folder and an extra row on the sheet, both of which you can see and delete. Marking first would instead lose a document quietly, and quietly is the one thing a register cannot afford.

A run reads at most 25 messages and files at most 'maxDocumentsPerRun' documents, which can be anything from 1 to 25. Whatever the cap leaves behind stays unlabelled and is picked up next time.

New mail is what wakes it, but the sweep is what does the work, so several documents landing at once are all picked up rather than only the first. Two things worth knowing. Gmail only hands over the attachments of a sender's newest message in the inbox, so if a supplier sends two documents within the same few minutes the older one cannot be opened - it is never dropped silently, the run log names it and says to forward it to yourself. And for the same reason the mail has to still be in the inbox when the run happens, so archive it after it has been registered rather than before.

Reading a document is a smart action, so an occasional run pauses for review before it finishes.

Fill in 'documentSearch' with a Gmail search that finds your document mail, 'boxFolder' with the Box folder to file into (its id, or the folder's address in Box) and 'registerSheetUrl' with the spreadsheet. 'documentFields', 'sheetTabName', 'processedLabel' and 'maxDocumentsPerRun' all have working defaults. Naming a sender on the trigger step narrows what wakes it; left empty, any new mail wakes it and your search decides what counts as a document.