Skip to main content
Automations are Suchi’s deterministic filing layer. Each automation combines one or more event filters with an ordered action list, lives in SQLite, and can be managed in the Automations screen or through the API. Human decisions belong in Approvals. Rules and their vocabulary belong to one filing system. Matching, offered categories, symbolic names and runtime metadata IDs stay in the document’s system; equal names/codes in S01 and S02 do not collide. Category assignment cannot transfer a document. Owner assignment requires an active member/admin of that system. Actorless custom-field document-link actions may target only live same-system documents; authenticated API links require separate source/target authorization. Disabled originals and edited forks survive reimport independently in each system.

​
Triggers

Triggers can filter by source path, filename, mail rule, tag, correspondent, document type, 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.

​
Actions

The visual builder exposes title, tag, correspondent, document type, Johnny.Decimal category, storage path, owner, and custom-field assignment. The JSON view remains available for inspecting the complete automation. The server exposes the current builder vocabulary and parameter schemas at GET /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. Assignment and removal actions are designed to converge when retried. 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. Example:
Title templates support {{title}}, {{correspondent}}, {{document_type}}, and {{date}}. Unknown placeholders remain visible so a typo does not silently erase text. Use IDs, not display names, in action parameters.

​
Classification order

For a newly extracted document Suchi runs:
  1. local archive matching, when enabled
  2. user automations in configured order
  3. the optional LLM classifier
Archive matching learns from authorized lexical neighbours and then applies review/auto-apply thresholds. Tokenization, BM25, ACLs, and its shared similar-document implementation are documented in Search architecture: Similar documents. The optional model has one confidence threshold. Confident validated results apply directly, while uncertain results keep current metadata, add needs-review, and can offer a title suggestion. See LLM classifier.

​
Preset ownership

Filing-tree presets seed a small starter set of automations. Editing a preset-owned automation creates a user-owned copy and disables the original. Reapplying a preset preserves the copy and the disabled original. Existing rule names remain local; imports report preserved/skipped rows rather than replacing them. The Automations screen keeps preset-owned entries in a collapsed Built-in automations list so user-created rules remain easy to scan. Taxonomy v1 imports only its explicit portable action subset, not every runtime action. Category skips skip whole dependent starters. Default taxonomy exports preserve supported preset-owned rule identity/order as named explicit starters, including keyword-generated rules; disabled/unrepresentable behavior fails. Tree-only export omits all starters. User-owned rules/forks require a complete backup. See Filing trees. Preset category keywords match case-insensitive whole words or phrases, not substrings: lease matches a lease document but not please. Migration 0002 repairs existing generated preset keyword rules. User-owned copies and other regex filters retain their explicit matching semantics. This correction does not refile previously processed documents. Review incorrect categories before relying on archive matching, which can otherwise reuse those documents as examples. Pre-release databases already at schema version 2 will not rerun that migration. Back up the database and apply only the final Repair preset keyword matching SQL block from core/db/migrations/0002_document_intelligence.sql once to those databases. That block is safe to repeat. Do not reset user_version or rerun the entire migration: its earlier statements create existing tables and columns.

​
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.

​
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.
  • Custom code cannot run as an automation action. Use a typed plugin instead.