---
module: transactions.journal-parsing
title: Journal Parsing Rules
tab: Internal
order: 20
audience: internal
---

Ops/support view of the **Journal Parsing** screen in the Transactions SPA (`transactions.bcos.cloud`). The screen edits the journal parsing rules and re-processes uploaded journal files. All the data and actions belong to the **hiveops-journal** service — the transactions backend only proxies the calls. See [technical.transactions].

## Who can use it

- Every admin action on this screen requires `hasAnyRole('MSP_ADMIN', 'BCOS_ADMIN')` — enforced in `AdminController` (hiveops-journal). A normal `USER`/`CUSTOMER` JWT gets **403** on rules edit, reload, types, and reparse.
- The file-status list (`GET /api/journal/files`) only requires `isAuthenticated()`, so a non-admin can still see file parse status but cannot act on it.
- The request path is: browser → `transactions` proxy (`/api/journal/**`) → `hiveops-journal`. The proxy forwards only `Authorization` + `Content-Type`, so the JWT reaches journal intact.

## What each panel does (and what it touches)

- **Journal Parsing Rules** — reads/writes the raw `journal-rules.yml` on the journal container. "Edit Rules" → "Save & Apply" hot-reloads the rules in memory (no restart). "Reload Rules" re-reads the file from disk. Both return the new rule **version**; a bumped version confirms the change took effect.
- **Journal / Vendor Types** — lists the vendor rule-set names defined under `journal_types:` in the YAML. Read-only here; you add types by editing the YAML.
- **Reparse Journals** — the destructive one. It **deletes the existing parsed transactions** for the matched files, resets them to `PENDING`, and re-queues them for async parsing. Blank ATM ID = every ATM. The reparse panel also exists as a fuller "Journal Reparse" view with an ATM/TCR tab, live parse-status pills, and a confirm modal.

## First things to check when it misbehaves

1. **403 on any button** — the JWT isn't `MSP_ADMIN`/`BCOS_ADMIN`. Confirm the logged-in user's role, not just that they're logged in.
2. **Rules won't load / save fails** — the error text comes straight from journal. A YAML validation failure returns **400** with `{"error": "..."}`. Fix the YAML and re-save; the version only bumps on success.
3. **Reparse says "Queued N" but files stay PENDING** — parsing is async and runs on the **worker** containers via Kafka. If workers are down or a deploy stranded files, they sit in PENDING. Run the journal **reconcile** endpoint (`POST /api/journal/admin/reconcile`, MSP_ADMIN) to re-publish stranded PENDING/PARSING files. This is the same post-deploy step documented for hiveops-journal.
4. **A new institution's files never parse** — files for an institution not listed in the journal `JOURNAL_INSTITUTIONS` env route to the `UNASSIGNED` topic/worker. They still parse (no data loss) but via the fallback worker. Onboard the institution properly if this is persistent.
5. **TCR files not showing / not reparsing** — the reparse and file-status views split ATM vs TCR by `journalType=NH_TCR`. Make sure you're on the correct tab; the "ATM" tab explicitly excludes `NH_TCR` files.
6. **Version didn't change after save** — a save that returns 200 always bumps the version. If it didn't, the request likely hit the wrong service instance or a cached rules object; reload the page and re-check.

## Common failure modes → fix

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| 403 on edit/reload/reparse | Non-admin JWT | Log in as `MSP_ADMIN`/`BCOS_ADMIN` |
| 400 "Invalid YAML or save failed" | Malformed rules YAML | Correct YAML, Save & Apply again |
| Reparse queued but PENDING sticks | Worker down / stranded after deploy | `POST /api/journal/admin/reload-rules`? no — run `/api/journal/admin/reconcile` |
| Files parse via unassigned worker | Institution not in `JOURNAL_INSTITUTIONS` | Add key + worker, redeploy journal |
| Old transactions still wrong after rule change | Rules changed but not reparsed | Run Reparse (blank ATM = all) after Save & Apply |

## Notes

- Reparsing rebuilds transactions from the **original journal files on disk**, so it is safe to re-run — but it clears current parsed rows first, so there is a brief window where transactions for those files are gone until parsing finishes.
- Adoons (the AI journey narrative) is unrelated to parsing rules; do not chase parsing bugs through Adoons.
