Parsing rules

A parsing rule turns a report email into a result: Healthy, Warning or Failed, and sometimes a job name, a size and a run time. BackupSentinel has built-in rules for the common backup products, and you can write your own. Rules live under Settings → Email parsing.

Built-in rules

Every built-in rule reads the result. Some also read more:

The job name matters when one client address receives several backups: it is how each report finds its backup. See Client addresses. The size is what makes a sudden drop show in Needs attention.

A Synology integrity check is not a backup run. It never resets the backup's clock, and a failed check opens its own alert that only a later passing check clears.

Each product has a setup guide in Setup guides.

How a rule is chosen

For each email, BackupSentinel tries the rules in this order and stops at the first one that matches:

1. Your workspace's rules first, then the library's built-in and community rules.
2. Rules with a subject pattern before rules without one.
3. First match wins. A rule matches when its subject pattern matches the email's subject. No other rule is tried after that, even if the matching rule finds no result.

The matching rule then reads the result:

• The subject is read before the body. If the subject contains any of the rule's keywords, the body is not checked.
• Failure beats warning beats OK. Report bodies often contain a summary table with every status word in it, so failure keywords are checked first. A wrong Failed is noise; a wrong Healthy hides a problem.
• Keywords ignore case and match inside longer words.

If a rule matched but none of its keywords appears, the email gets No result read and the backup's status does not change. The generic keywords are not tried in that case.

When no rule matches

If no rule's subject pattern matches, BackupSentinel falls back to a fixed set of words: "failed", "failure" and "error" for a failure; "warning" and "warn" for a warning; "success" and "completed successfully" for a success. The same order applies: subject first, failure first.

The fallback reads no job name and no size, and it is easy to fool. Other software lists its pitfalls and when to write a rule instead.

Writing a rule

Click New template on the Email parsing page, or Create rule on an email in the Inbox. Owners, admins and members can create and edit rules. The fields are:

A custom rule has no duration field.

An example for a product whose subjects look like "NightlyVault: job FS01 finished (OK)":

Subject pattern:   ^NightlyVault: job
Failed keywords:   (FAILED), aborted
Warning keywords:  (WARNING)
OK keywords:       (OK)
Job name pattern:  job (\S+) finished
Size pattern:      Transferred:\s*([\d.,]+)\s*(TB|GB|MB|KB|B)

Pattern limits

Patterns are checked when you save, so a rule never fails silently later:

• At most 200 characters per pattern.
• Patterns that can take exponentially long to run are rejected: a quantified group that itself contains a quantifier or an alternative, such as (a+)+ or (\w|\d)*, and quantifiers placed straight after each other.
• The job name and size patterns need a capture group.
• Only the first 100,000 characters of an email (subject and text together) are read.

Testing a rule

The editor has Test against a sample email. Paste a real Sample subject and Sample body from the product. As you type, it shows whether the subject matches, and the status, job name and size the rule reads.

In the Inbox, each email shows the rule that read it. Test this rule on this email shows what that rule reads from the email today, which is useful after you change a rule.

Changing a rule does not re-read emails already stored. To apply a rule to an email that is waiting in the Inbox, assign it to its backup.

The library

Browse library opens the rules shared with every workspace, under Built-in and Community.

• Customize makes an editable copy of a library rule in your workspace. Your copy runs before the original. Revert deletes your copy, and the original takes over again.
• Share proposes one of your own rules for the library, with an optional note for the reviewer. BackupSentinel reviews every proposal before it is published to all workspaces. While it waits, the rule shows "Awaiting review", and you can withdraw it. A declined proposal can be changed and resubmitted.

Deleting one of your rules keeps the history of the emails it read. New emails no longer use it.

The Inbox

Every email that reaches a client or backup address is listed in the Inbox under All emails, with one of these outcomes:

Needs review lists the Not assigned and No result read emails. For each one you can:

• Start monitoring: create a backup from the email and assign the email to it, within your plan's job limit.
• Assign to a backup…: link it to a backup that already exists.
• Create rule: open the rule editor for emails like this one.
• Ignore: remove it from Needs review. Emails from one sender can be ignored together, up to 500 at once. An ignored email stays under All emails, and Restore to Needs review brings it back.

Superseded explained

Reports do not always arrive in order: a delayed forward or a resent email can arrive after a newer one. A report that is older than the backup's last report is kept, but it does not overwrite the newer result. If a Superseded email belongs to a different task, that task needs its own backup.

Daily caps

• 100 reports per backup in 24 hours.
• 200 unmatched emails per client in 24 hours.

Emails over a cap are not stored. They exist to stop a loop from filling your history, and a normal schedule never reaches them.

Limits

• A rule matches on the subject only. Two products with the same subject wording need patterns that tell them apart.
• Custom rules read the result, a job name and a size. They cannot read a duration.
• Changing a rule does not re-read emails already received.
• Only the first 100,000 characters of an email are read.
• Shared rules are published only after review by BackupSentinel. There is no voting.