KeepsakeHow do I make a document app file things automatically?
How do I make a document app file things automatically?
Write rules of the form "when a document matches this, do that". Each rule tests what arrived — the file name, the recognised text, the sender, the size — and then sets a category, adds tags, renames it or sets a reminder. Keep the rules in order, let the first confident one stop the rest, preview them against documents you already have before running them, and never let a rule delete or move anything.
Filing is not hard. It is small, dull and endless, which is worse: forty scans a year, each one needing a category, a sensible name and a date somebody will care about in eleven months. Most people do it for a fortnight and then stop, and the vault becomes a pile with search over it.
The fix every serious document system arrives at is the same one, and it has a name now — workflows, or rules. You describe the filing once, as a sentence: when a PDF arrives from the council mentioning council tax, file it as a bill, tag it council, name it by the issuer and remind me four months before it expires. After that the filing happens as the document lands, and you check it rather than doing it.
This guide is about how to write rules that are still right in a year, and about the one property that decides whether automatic filing is safe to turn on at all: what a rule is not allowed to do.
What a rule is made of
Four parts, and no more than four, or nobody can read their own rules six months later.
- When it listens. Which arrivals wake it up — a watched folder, a saved email, a bulk import, a document you added by hand.
- What it matches. One or more conditions over what arrived. All of them, or any of them; that choice is the rule's and not a global setting.
- What it does. One or more actions, applied in order.
- Where it sits. Rules are a list, not a set. The order is the rule.
The conditions are over things a document actually has when it arrives: the file name, the recognised text, the extension, the size, the title, the category it was given, its tags, its issuing authority, its reference number, and — for something that came out of a mailbox — the sender and the subject line. The operators are the ordinary ones: contains, does not contain, is, is not, starts with, ends with, matches a regular expression, is empty, is not empty, and for a size, is larger or smaller than.
An operator only offers itself for a field it makes sense on. "Larger than" is not offered for the sender, and "starts with" is not offered for a file size — an editor that lets you write a condition that can never be true has wasted your afternoon politely.
The five moments a rule can fire
| Trigger | Fires when |
|---|---|
| Watched folder | A file lands in the folder your scanner or your phone drops into. The common case, and the one worth writing rules for first. |
| Email attachment | A document is imported out of a saved message or a mailbox check. This is the trigger where the sender and the subject are worth matching on — an attachment called document.pdf from your insurer is not ambiguous at all once you look at who sent it. |
| Folder import | A bulk import: a vendor export, an old backup, a directory of scans from before you had a system. |
| Added by hand | You picked a file and imported it yourself. Worth leaving on — the rule still saves you the category and the name — and worth turning off on a rule you are not sure about yet. |
| Documents already filed | Not an arrival at all. This one is off by default, and is how you apply a new rule to the pile you already have. It is the trigger that needs a preview, and gets one. |
A rule with no trigger ticked is a rule that never runs, so it is refused when you save it rather than sitting there looking active.
Order, and the rule that stops the rest
Rules run from the top. Every rule that matches is applied, in order, and a later action overwrites an earlier one — which is exactly what you want when the last rule is the general one and the first is the specific one.
The single action worth understanding properly is stop. A rule that ends in stop is saying: if this matched, I know what this document is, and nothing below me should second-guess it. Put the confident rules at the top, end them with stop, and let the vague catch-alls sit underneath where they can only touch what nothing else claimed.
The failure this avoids is the one that makes people give up on automatic filing: a broad rule near the bottom quietly re-categorising documents that a precise rule near the top had already got right, and nobody noticing for three months.
What a rule may do — and what no rule can do
Seven actions. The list is short on purpose, and every one of them is additive: it sets a field, adds a label, or writes a note.
| Action | What it does |
|---|---|
| Set the category | Files it — as a bill, a policy, an identity document, or one of your own categories. |
| Add a tag | Adds one label. Tags are added, never replaced, so two rules can each contribute one. |
| Set the title | Renames it from a template: {authority} council tax {today} beats scan_00412.pdf in any search you will ever run. |
| Append a note | Adds a line to the document's notes — where it came from, which rule filed it, what you will want to know later. |
| Set the issuer | Fills in the issuing authority when the document did not say so in a way the reader could find. |
| Set the reminder lead | How many days before the expiry date you want telling — for this document, because a passport and a parking permit do not deserve the same notice. |
| Stop | No further rules run on this document. |
No rule can delete, move, share, export or overwrite a document. That is not a setting that ships switched off — there is no such action in the list at all, and there is no way to write one. A rule can be wrong about a category; being wrong then costs you a category, which you fix in four seconds. If it could be wrong about deleting, being wrong would cost you the document.
It is worth saying plainly why this matters more than any feature the list is missing. Automatic filing is only worth turning on if the worst case is mild. The moment a rule engine can move files out of the vault or empty a folder on a match, every rule you write becomes a small decision about risk, and the honest response to that is to not use it. A rule set that can only add information is one you can leave running and forget about.
Naming documents from what is in them
The two actions that take a template — the title and the note — can quote what the document actually contains, so the name is written from the document rather than from your memory of what you were doing that afternoon.
{filename} {title} {category} {number} {authority} {sender} {subject} {today} {issued} {expires}
A placeholder for something the document does not have becomes nothing at all, rather than the word "null" or a set of empty braces sitting in the middle of a title for the rest of the document's life. Council tax {authority} {issued} on a document with no issuer reads as Council tax 2026-04-01, and that is fine.
Preview before you run rules over what you have already filed
New rules are usually written because of the pile, not because of the next arrival — you have four hundred documents and you have just worked out how twelve of them should have been filed. Running rules backwards over documents you already have is the most useful thing a rule engine does and the most alarming, because it changes many things at once.
So it is previewed. Before anything is written, the same rules run over the same documents with nothing saved, and you are shown the count and the changes: "14 documents would be changed." If the count is 380, the rule is too broad and you have learned that for free.
What makes that preview worth trusting is that it is not a second implementation describing the first. It is the same code path, run with the writing switched off — the difference between "we tested the preview" and "the preview cannot disagree with the run, because it is the run".
Rule files you can send to somebody
Rules are worth writing once for a household, not once per person, and worth publishing when they are good. So a rule set exports as a small JSON file — a plain, readable list of rules with a kind and a version at the top of it, and nothing else.
Nothing in the file is about the vault it came from. No document, no path, no account, no key: it says when a file name contains "council tax", file it as a bill, and that sentence is as true on your sister's machine as it is on yours. An imported file is added to the rules you already have rather than replacing them, and it is checked on the way in — every rule that is malformed, over the ceiling, or names a category that does not exist on this machine is reported by name, all of them at once rather than one per attempt.
Sensible ceilings
A rule builder with no ceilings becomes a programming language, and then a slow one. The limits are deliberately low enough to keep rules readable: 60 rules, 10 conditions and 10 actions in each, 60 characters of rule name, 200 of a condition value, 160 of a template. A regular expression that takes longer than a moment to run is abandoned rather than allowed to hang an import.
If you need more than sixty rules, the thing you actually need is fewer, broader rules and a category or two.
Step by step
- Start with the document you file most often. Not the interesting one. The council tax bill, the payslip, the insurance renewal — the arrival that happens monthly is where a rule pays for itself.
- Write the narrowest condition that identifies it. A phrase from the recognised text usually beats the file name, because scanners name things badly and documents say what they are.
- Give it a category, a tag and a name. Three actions is a good rule. Add a reminder lead if the document expires and the default notice is wrong for it.
- Put it above the vague rules and end it with stop. Specific first, general underneath. Stop is what keeps a broad catch-all from undoing a precise match.
- Preview it against what you have already filed. The count tells you whether the rule means what you thought. A rule that would change 380 documents is a rule that matches on nothing in particular.
- Run it, then leave it alone. Check the next few arrivals it touches. Once a rule has filed a document correctly three times, it will keep doing it.
Questions
Can a rule delete a document, or move it out of my vault?
No, and not because it is switched off — there is no delete, move, share or export action in the rule engine at all, so there is nothing to switch. The seven actions set a category, add a tag, set a title, append a note, set the issuer, set a reminder lead, or stop the rules below. A rule that gets a document wrong gets a field wrong, and you fix it in seconds.
What happens if two rules disagree?
The later one wins, because rules run in order and the last action to set a field is the one that stands. That is a feature when your general rules sit under your specific ones, and a nuisance when they do not — which is what the stop action is for: a confident rule ends with it and nothing below runs.
Will rules change documents I have already filed?
Only if you ask. The trigger for documents already in the vault is off by default on every rule, and running it is a deliberate act from the rules screen that shows you how many documents would change before anything is written.
Can I use a regular expression?
Yes, on any text field, and it is checked when you save the rule rather than when a document arrives at two in the morning. An expression that runs too long is abandoned rather than allowed to hang the import.
Does this work on my phone or in the browser?
Windows only today, and the omission is a decision rather than a gap. Rules earn their keep on the doors documents arrive through in bulk — a watched folder, a mailbox, a vendor export — and those are all on the desktop. On a phone you import one document at a time while looking at it, which is the case where filing it yourself is genuinely faster than describing it.
What does the app do when a rule fires?
It writes what changed into the document's history, in the same hash-chained audit log that records your logins and imports. "Why is this filed as a bill" always has an answer, and the answer names the rule.
Can I share my rules with someone else?
Export them. You get a small JSON file describing the rules and nothing else — no documents, no paths, no account — which imports on any other copy and is added to the rules already there rather than replacing them.
Where Keepsake fits
Keepsake is our product, so read this part with that in mind. Everything above is true whether or not you use it, and most of it you can do with a folder and an afternoon.
In Keepsake this is the Rules screen, next to your own fields and your own categories. Rules run on all four doors documents come in through: the watched folder, an email attachment, a folder import, and a document you add yourself. A reminder lead a rule sets is honoured by the same renewal reminders everything else uses.
What decides all of it lives in one file, shared/workflows.json — the triggers, the fields, the operators, the seven actions, the ceilings and the exact wording of every refusal. This page is a copy of that file, which is why the wording here is the wording the app uses. The suite behind it asserts the negative as well as the positive: it fails if an action that deletes, moves, shares or exports a document is ever added to the pack.