Triggers
Triggers can filter by source path, filename, mail rule, tag, correspondent,
title or content regex, sender, subject, mailbox folder, and attachment
presence. Multiple filters on one trigger use AND. Multiple triggers on an
automation use OR. A filename filter matches an email attachment by its own
attachment name.
document_updated fires from exactly two places: PATCH /api/documents/{id}
(title, title release, sensitivity, category, folder layout, archive serial
number, or languages) and the bulk set_correspondent, set_rendered_layout,
set_jd_category, set_sensitivity, add_tag, and remove_tag methods.
Adding or removing a single document’s correspondent link, setting or clearing
a custom-field value, editing notes, uploading a version, and the lifecycle bulk
methods (trash, delete, restore, rescan) do not emit it.
These rules run synchronously before the successful API response, so their
execution adds to request latency. A bulk edit runs them once per unique
authorized document, in request order, after the shared metadata transaction
commits. Rule failures are fail-soft: Suchi logs the failure, keeps the
committed edit, and continues with later documents. Once the edit has
committed, its rules run to completion even if the client disconnects.
Actions
The visual builder exposes title, tag, correspondent, filing category, folder-layout, owner, and custom-field assignment. Folder layouts, eligible owners, and custom fields use named pickers; the value editor follows the selected custom field’s declared type. The API continues to persist their IDs. A layout that uses the archive serial number fails atomically for a document without one. The screen lists every rule in run order. The JSON view remains available for inspecting the complete automation. The server exposes the current builder vocabulary and parameter schemas atGET /api/automations/schema. Actions run in order inside one transaction;
failure rolls back that automation and is recorded in structured logs. Trigger
types and glob or regular-expression filters are validated when a rule is
saved, so malformed rules do not silently sit idle.
Automations do not re-trigger themselves from their own writes, so dependent
actions should stay in one automation. Title, tag, correspondent, category,
folder-layout and owner actions queue the matching rendered-folder move in that
same transaction when their effective path input changes.
Assignment and removal actions are designed to converge when retried. Replaying
an already-converged action does not queue another rendered-folder move.
discard is idempotent for an already-trashed document and retains its original
Trash timestamp. Other metadata actions still require a live document; discarding
does not grant a rule permission to edit Trash or cross a filing-system boundary.
assign_title claims rule ownership. It may replace an automatic title, and a
template without {{title}} may refresh a title previously assigned by a rule,
including during Refile. Every rule skips a title renamed or approved by a
person.
A template containing {{title}} applies only while the title is automatic.
After the first application, rule ownership prevents retries, Refile, or later
updates from feeding the generated title back into itself. Rules still run in
order: a fixed rule can replace a title set by an earlier self-referential rule,
while a fixed rule that runs first prevents a later self-referential rule from
consuming its result.
On the document screen, Unpin returns the title to automatic naming without
changing its text. That makes the retained text eligible for model naming or
one application of a self-referential rule.
Title templates support {{title}}, {{correspondent}}, {{tags}}, and
{{date}}. Placeholders are replaced in a single pass, so placeholder-like text
inside a substituted value stays literal. Unknown placeholders remain visible
so a typo does not silently erase text. The visual builder resolves names to
IDs; direct JSON action parameters continue to use IDs.
Examples
These build from one filter and one action up to a mail-intake rule. The classifier examples below add a model-answered question. IDs refer to your own tags, correspondents and categories. Title and content patterns are case-insensitive regular expressions; path, filename, sender and subject filters are globs.File utility bills
One content filter, one category.Invoices in any language
Patterns match the extracted text as written, so one rule can cover every language your documents arrive in. Japanese and Chinese have no spaces between words, so a term matches wherever it appears.Supplier mail with attachments
Mail filters are available while the source message is known, at consumption. Every filter on one trigger must match; actions run in order in one transaction.Ask the classifier
An administrator can attach one closed question to adocument_added
automation. The Automations builder supports Yes / No or 2–10 named choices;
unknown is always added as a no-action answer. At most five enabled question
automations may exist in one filing system.
Question automations use only state available after extraction: title/content
regular expressions plus existing tag and correspondent filters. Intake-only
path, filename and mail-envelope filters are rejected. Matching is recomputed
for each eligible classifier job, including an explicit LLM rescan. Refile and
document_updated events do not invoke the question branch.
Each action names the answer that activates it. Supported effects are adding
existing tags, assigning one existing correspondent or filing category, and
setting a fixed typed custom-field value. Document-link custom fields are not
available. Destinations and fixed values remain in Suchi; the model receives
only the automation ID, question text, and allowed answers. It cannot choose an
action, metadata ID, or arbitrary value.
Example: warranty proof
Ask whether warranty language constitutes proof, then set an existing boolean field and add an existing tag. IfWarranty proof already has a value, Suchi
preserves it and can still apply the independent tag.
Example: tax document type
A multiple-choice branch can file an invoice or mark a credit note without letting the model invent a category or tag. Category assignment applies only while the document is in Inbox.Example: contract renewal clause
Use a narrow content filter so only likely contracts receive the question. Theyes branch records a fixed flag and review tag; no and unknown leave
the document unchanged.
unknown—include a short exact quote from the
document. Duplicate IDs, invented answers, and ungrounded evidence are ignored.
Question definitions and their ordered match set are compared again in the final
write transaction; if that set changed during the provider call, every question
answer from the call is discarded while ordinary classifier output may still
apply.
Answer actions use the same confidence threshold and automatic/review-first
setting as ordinary classifier metadata. A review card names the automation and
the proposed fixed effect. Suchi does not retain the question, raw answer, or
evidence quote as ask history; normal audit and approval records retain only
bounded automation attribution and metadata-change provenance.
Classification order
For a newly extracted document Suchi runs:- local archive matching, when enabled
- ordinary user automations in configured order
- the optional LLM classifier, including questions from matching ask automations
0.90 apply; the default minimum score for review suggestions is 0.50.
Both thresholds are configurable. Turn automatic mode off to review inferred
changes before application. Tokenization, BM25, ACLs and shared retrieval are
documented in Search architecture: Similar documents.
The optional model shares that mode, with a default metadata/date threshold of
0.70; each date uses its own score. Below-threshold changes remain suggestions.
Current source, access and field-generation checks still protect human changes
and explicit rule writes, including clears and same-value reassertions.
Classifier-owned needs-review markers are excluded from rule matching and
templates so a machine-created marker cannot activate a destructive rule.
Explicitly adopted or rule-assigned tags remain ordinary rule input. This does
not introduce model-authored external actions or change explicitly configured
internal automation behavior. See LLM classifier.
No built-in rules
Filing trees carry no automations; every rule belongs to the archive that created it. Upgrading removes the rules earlier presets installed. A built-in rule you edited was already saved as your own copy, so it stays. Taxonomy import and export cover the filing tree only; rules move with a complete backup.API
Automations use/api/automations/; updates replace supplied trigger and
action arrays wholesale. Writes require administrator access. Complete
payload and error contracts live in API.
Every successful metadata mutation is audited. Failures include the document
and action kind in structured logs without document content.
Compiled actions
core/automations.ActionDefinition pairs a unique Kind, Validate callback and
Execute callback. NewRegistry copies definitions into an immutable instance;
there is no default registry or runtime registration method. Assembly explicitly
combines BuiltinActions() with app.Options.Actions, then passes the same
registry to rule storage, API document updates, ingestion and refiles. Standalone
callers must supply their registry too; unknown kinds retain unsupported kind
errors. The existing builder schema continues to advertise the community visual
builder’s subset; compiled actions can be configured through the JSON API.
Validate(ctx, tx, systemID, params) reads configuration/references in the
caller’s transaction, both on save and immediately before execution.
Execute(ctx, tx, ActionTarget{DocID, SystemID}, params) receives the current
live document’s system and the same writer transaction as every action in that
rule. Only the built-in idempotent discard may revisit Trash. A failure rolls
back the entire rule, including extension state and enqueued jobs. Preserve
idempotence with domain constraints/receipts because jobs and refiles can retry.
Callbacks must be concurrency-safe, and validation must only read. Do not commit
or roll back the supplied transaction, re-enter the writer, or call network or
subprocess services while holding it.
Callbacks are trusted code compiled by the distribution, not scripts supplied by
an API user. Rule CRUD still requires the existing administrator boundary;
document admission, system ownership, ACLs, approvals and audit remain Suchi’s
responsibility. A target is not a principal or permission to operate on other
documents. New actions must validate their references within that system and
preserve the callers’ authority. This registry does not add inferred actions,
external workers, or a new approval path. See Plugins.
Current limits
- Filters are structural plus title/content regexes, not an arbitrary expression language.
- There are no scheduled triggers or built-in user-notification actions.
- Runtime scripts cannot be installed as actions; additional handlers require a compiled distribution.