Your first coding rule

A rule is a standing instruction: when an invoice looks like this, code it like that. The point is not automation for its own sake. It is that you should never have to make the same coding decision twice, and that the decision should be written down somewhere your colleague can read it — rather than living in the head of whoever normally does the invoices and going on holiday with them.

By the end of this page you will have one rule saved, simulated and confirmed firing on real mail.

Before you start

• You need to be an Admin or a Controller Approver. An AP Specialist sees the whole list and a greyed New rule button, with the reason printed beside it.
• You need a paid plan. Rules and approval tiers are one feature and it is not included on the Free plan, where invoices are processed and coded by hand. So if you are already paying and the button is still greyed, ask for the role rather than for an upgrade.
• Bring a decision you have already made. The best first rule is not hypothetical: a vendor whose invoices you have coded identically three times running, and the GL code you gave them.
• Know who should look at it. If the rule assigns a reviewer or an approver, that person must already be a member of the workspace. The builder offers your own members, and a name nobody answers to is a rule that quietly assigns nothing.

1. Pick the decision, and put a ceiling on it

Open the Inbox and find the vendor. The classic is a landscaping contractor: every invoice goes to the same property and the same grounds maintenance account, and has done since the contract was signed.

Then decide the amount above which you do not want the rule to act. Without a ceiling, the day the landscapers send a $40,000 grounds redevelopment invoice it is coded to routine maintenance and treated like a lawn mowing. A ceiling is cheap insurance against the unusual invoice, and the unusual invoice is the one that hurts.

2. Open Rules and press New rule

Rules live on the Rules screen in the left-hand navigation. New rule is at the top right. Pressing it clears the builder and tells you so — nothing has been written yet.

The left-hand column is the rule order, and it says what the order means: the lowest priority number runs first, and rules sharing a priority run oldest first.

3. Write the conditions

The builder's condition panel is headed If all of these are true. Conditions combine with AND, so every one you add narrows the match. Add condition adds another row.

A rule matches on these six fields, and only these. Each understands only the operators listed against it:

Two of them repay a moment's attention.

There is no domain field. Matching a whole vendor domain is Source email contains "@greenacreland.com", which reads a little oddly the first time and is exactly right: it catches billing@, accounts@ and whichever new address their bookkeeper starts using next spring.

"Keyword in document" reads the subject line. Not the body, not the PDF. It is useful for vendors whose subject lines carry a job number or a building name, and useless for anything printed inside the invoice. The name is more generous than the behavior, so plan around the behavior.

For the landscaper, two conditions:

Source email  contains       @greenacreland.com
Amount        is less than   2500

4. Choose the actions

The action panel is headed Then do this, and Add action adds another. There are five:

For the landscaper:

Set coding        6300
Assign reviewer   Priya Raman

Assign reviewer and Assign approver both pick from the people in your workspace, so the builder cannot offer you somebody who is not there. The name is matched against your own members when the rule runs, and if it matches nobody, the document is left unassigned and nobody is asked — never handed to a stranger with a similar name. They are different jobs: a reviewer checks and codes the invoice, an approver signs for it.

Auto-approve is opt-in and worth being deliberate about. A sensible first use is small, high-confidence invoices from a vendor you have mapped — the ones that would have reached the approval queue anyway, only more slowly. You choose Yes or No; the builder offers the two answers rather than a box to type in.

5. Name it, and leave the priority alone

Type a Rule name a colleague would understand in a year. Leave Enabled on, and leave Priority at its default of 100 for your first rule. The box takes whole numbers from 0 to 1000, and you only need it once a rule genuinely has to settle a field before another rule reads it.

6. Simulate before you save

Press Simulate. The draft is sent to the server, which replays it over the invoices your workspace already holds and answers under Simulation: how many matched, out of how many it read, and a table of the matches showing the invoice, the vendor, the amount and what your rule would do to it. Each row links to the real document, so you can open one and check the rule against it.

The simulation changes nothing. No invoice is coded, routed or held, no audit entry is added, and no rule's match count moves. It is a read, so an AP Specialist who cannot save a rule can still run one and take the result to the Admin or Controller who can. Rules are part of a paid plan, so on the Free plan the button is disabled and gives the reason.

Four things about the answer are worth knowing before you act on it.

It reads a window, not your whole history. The simulation takes your most recent invoices, newest first, and the result line prints how many it actually read and the dates they cover. An older invoice this rule would match may simply not have been looked at. When there are more matches than the table can list, it shows the most recent of them and says what it cut them from. The rules reference gives the exact bounds.

It reads only what the rules engine reads. A document still waiting on extraction, and one already set aside as not an invoice, are both skipped — the engine never sees those either. An invoice becomes eligible once extraction has finished with it. A workspace whose mail all arrived in the last few minutes therefore has invoices and still has nothing to simulate against, and the card says exactly that rather than reporting zero matches. If you are property-scoped, the simulation covers your own buildings, which is the same set of invoices you see in the Inbox.

Zero matches is a result, and often the right one. A rule written for mail you have not received yet matches nothing today and will still fire when it arrives. So read zero as a fact about that window rather than as a failure — then check the usual mistakes anyway: a domain typed without its @, an amount comparison the wrong way round, a keyword condition expecting to read the document body.

A match is not the same as a rule that fires. Your draft is evaluated inside the enabled rules, in priority order, in the place it would occupy if you saved it. Quarantine stops the chain, so an enabled quarantine rule that runs before yours and matches the same invoice means yours never runs on it. The row says so — Never reached, naming the rule that quarantines the invoice first — and the summary counts how many of your matches would never fire. The fix is a lower priority number, which puts your rule earlier. This is the one thing you could not learn from sample invoices, and it is the reason to simulate at all.

One caveat covers the whole answer: matching uses today's vendor mappings and property aliases. So the simulation tells you what this rule would do to these invoices now, not what would have happened when they arrived. A vendor you mapped this morning counts as mapped for every invoice in the window, including the ones that arrived before you mapped it.

7. Save it

Press Save rule. A confirmation tells you the rule was created. If the API refuses a condition or an action, the message says which one rather than failing silently.

You should now be looking at the rules list with your rule in it, showing its priority and 0 matches in total, and the builder still holding what you typed.

8. Check it actually fired

A saved rule is not a working rule. Come back the next working day and check three things.

1. The match count on the rule row. If you wrote a rule this morning and it has matched nothing by tomorrow, the rule is wrong, not the world. The usual culprits are a keyword condition expecting to read the document body, a domain typed without its @, and an amount condition in the wrong direction. The count is a lifetime total, so it only ever goes up.
2. The document. Open one of the vendor's invoices from the Inbox. The GL code should be there with no person's name against it, and the reviewer you named should be on it.
3. The Audit Log. It records, for each document, every rule that fired on it, and the GL code itself records the rule that set it. A document coded in a way nobody expected can be traced back to the instruction that did it — which is also how you answer "why did this one go through automatically" three weeks later.

How rules combine

Every rule that matches is applied, in priority order: lowest number first, and rules on the same number oldest first. Write each rule so that it is correct on its own, and use the number only when order genuinely matters.

Quarantine stops the chain. Nothing after it runs, which is the point — a document held for a security reason should not then be auto-approved by a later rule that only looked at the amount.

Everything else accumulates. A general rule that sets the GL code and a specific one that assigns a reviewer will both apply, provided both match.

A second rule: the mailbox one

If you have given a building its own intake address, a rule can act on it:

Intake mailbox  contains  lakeshore@

Use contains with the local part rather than typing the whole address. The rule then survives a change of intake subdomain, which a full address does not.

You may not need this rule at all. A mailbox created with a property already codes mail arriving there to that property when the invoice names nothing your aliases recognize. Reach for the rule when the mailbox should also set a GL code, assign a particular reviewer, or apply only to some of the mail arriving there.

Where to go next

• Rules reference — every field, operator and action in detail.
• Approval tiers — who has to say yes, and by when.
• Coding invoices — what you are actually setting when you code.
• Per-property mailboxes — when an address is a better tool than a rule.