diff --git a/guides/app-features/transactions.mdx b/guides/app-features/transactions.mdx index 4e63e12..739e1a3 100644 --- a/guides/app-features/transactions.mdx +++ b/guides/app-features/transactions.mdx @@ -94,6 +94,38 @@ Sure prevents merges that would make the category hierarchy confusing or invalid If a source category has subcategories and the target is a parent category, Sure reparents those subcategories under the target. +## Transaction rules + +Rules let you automatically apply actions to transactions that match a set of conditions. You can build rules from **Settings → Rules**. + +### Condition filters + +The rule builder supports the following condition types for transactions: + +| Condition | Operators | +|---|---| +| Transaction name | Contains, Does not contain, Equal to, Is empty | +| Transaction amount | Greater than, Less than, Equal to | +| Transaction category | Equal to, Is empty | +| Transaction merchant | Equal to, Is empty | +| Transaction tag | Equal to, Is empty | + +The **Transaction tag** condition lets you match transactions that already have a specific tag applied. Use it together with the **Set tags** action to build tag-based routing rules, or combine it with other conditions using AND/OR logic. + +### Actions + +Rules can apply the following actions to matching transactions: + +- Set category +- Set merchant +- Set name +- Set tags +- Add note + +### Export and import compatibility + +Tag-based rule conditions survive an export/import round-trip. When you export your data and re-import it, tag names are remapped correctly so tag conditions continue to work as expected. + ## Related pages - [Budgets](/guides/app-features/budgets) diff --git a/guides/knowledge-base/troubleshooting.mdx b/guides/knowledge-base/troubleshooting.mdx index b381d03..8410fad 100644 --- a/guides/knowledge-base/troubleshooting.mdx +++ b/guides/knowledge-base/troubleshooting.mdx @@ -233,6 +233,38 @@ Self-hosted users running a local model (Ollama, LM Studio, etc.) may see the ch +## Sure NDJSON import fails with a missing field error on rules or rejected transfers + +Importing a full `all.ndjson` export may fail preflight validation with errors about missing required fields, even when the export file is valid. + + + + Earlier versions of Sure required the `name` field to be present for each rule during preflight. However, rule names are optional in the data model and can be `null`. A single rule with `"name": null` would block the entire import. + + This has been fixed. Preflight now validates the rule `id` field instead of `name`, matching what the importer actually needs. Exports containing rules with null names import successfully. + + + + A `RejectedTransfer` record whose referenced transaction was deleted after the export was created previously caused a hard error during preflight, blocking the import. + + This has been fixed. Orphaned rejected transfer references are now treated as warnings rather than errors. The importer skips the orphaned row and counts it as skipped, so the rest of the import proceeds normally. The preflight response includes a warning message for each skipped row. + + + +## Excluded transactions disappear from account activity + +If you exclude a transaction from analytics and it no longer appears in the account activity list, you cannot toggle it back on from that view. + + + + Earlier versions of Sure filtered the account activity list to only show non-excluded entries. This meant excluded transactions — including investment trades excluded from analytics — were hidden entirely, with no way to re-include them from the account view. + + + + The account activity list now shows excluded transactions in a greyed-out state, matching the behavior of the global Transactions page. You can click an excluded entry to open its detail drawer and toggle exclusion back off. Only split parent entries remain hidden, as they are internal bookkeeping rows. + + + ## Why is Sure not running auto-categorization and merchant detection on the same transactions again? Sure caches AI-generated results to avoid redundant API calls and costs. Once a transaction has been processed by AI rules, it won't be re-processed unless you explicitly reset the AI cache. diff --git a/providers/simplefin.mdx b/providers/simplefin.mdx index 9dff550..b1011fa 100644 --- a/providers/simplefin.mdx +++ b/providers/simplefin.mdx @@ -102,6 +102,12 @@ Generate a new setup token from your SimpleFIN dashboard. Some institutions don't return pending transactions even when the `pending=1` parameter is set. This is a limitation of the institution's data feed, not a bug in SimpleFIN or Sure. +### Duplicate accounts with the same name + +If you have two accounts at the same institution with identical display names (for example, two accounts both named "CHECKING (0001)"), Sure uses the upstream account ID to distinguish them during sync. Accounts are only considered stale and eligible for re-linking when their upstream account ID is genuinely absent from the latest sync response. Same-name ambiguity is detected and skipped rather than silently merging the wrong accounts. + +If you notice transactions or balances appearing on the wrong account after a sync, disconnect and reconnect your SimpleFIN token to force a clean account discovery pass. + ### Network errors If you experience intermittent sync failures: diff --git a/self-hosting.mdx b/self-hosting.mdx index 0d79c4f..eead820 100644 --- a/self-hosting.mdx +++ b/self-hosting.mdx @@ -481,6 +481,59 @@ For production deployments: - Use `SMTP_OPENSSL_VERIFY_MODE=peer` - If you must use self-signed certificates, provide a CA bundle via `SSL_CA_FILE` +## Monitoring system health + +Super-admins can check the live state of the background job worker from **Settings → Advanced → System health**. + +The page shows: + +- Number of active Sidekiq worker processes +- Last heartbeat timestamp +- Maximum queue latency +- Job counters (processed, failed, enqueued, scheduled, retries) +- Per-queue depth breakdown + +### Sidekiq health banner + +When the Sidekiq worker is not processing jobs, a warning banner appears at the top of every page for super-admins. The banner explains that data may be stale and links directly to the system health page. + +Common reasons the worker may be unhealthy: + +- The `worker` container is not running (most common in Docker Compose setups) +- Redis is unreachable +- No heartbeat received within the last 2 minutes +- Queue latency exceeds 5 minutes + +If you see the banner after starting Sure, verify the worker container is running: + +```bash +docker compose ps worker +docker compose logs worker --tail 50 +``` + +If the worker is stopped, restart it: + +```bash +docker compose up -d worker +``` + +### Tuning health check thresholds + +The default thresholds work for most deployments. If your environment has slower Redis or longer-running jobs, you can override them with environment variables: + +```txt +# Seconds before a process heartbeat is considered stale (default: 120) +SIDEKIQ_HEALTH_HEARTBEAT_TIMEOUT=120 + +# Seconds of queue latency before the worker is considered unhealthy (default: 300) +SIDEKIQ_HEALTH_LATENCY_THRESHOLD=300 + +# Seconds to cache the health snapshot (default: 60) +SIDEKIQ_HEALTH_CACHE_TTL=60 +``` + +The system health page always bypasses the cache and shows a fresh snapshot. + ## Troubleshooting ### Database connection errors