Cases

What it does

cases is a bundled iframe module for legal matter and case management (Akten/Mandate): each case carries a client (Mandant), an assigned lawyer, workflow status, priority, practice area, court references, an opponent summary, and a conflict-check state. Around the core record it manages parties, key dates (deadlines, hearings, filings, limitation dates), a communication log, and links to existing Clapilot documents, tasks, calendar events, emails, drafts, and notes — plus a combined timeline over all of it.

How to open it

• Web: /modules/cases (bundled module, slug cases); deep-link a case with ?case_id=<uuid>, and the UI language follows the ui_language parameter (de/en/it, default de).
• Manifest: bundled-modules/cases/module.json; UI: bundled-modules/cases/index.html (iframe renderer); API: bundled-modules/cases/api/handler.mjs.
• The module is bundled; it starts uninstalled on new minimal-policy instances and remains installed on grandfathered legacy-policy instances. Admins can install or uninstall it from the module store. It does not require developer mode.
• The database schema (legal_cases and related tables) is created automatically on the module API's first request from bundled-modules/cases/migrations/001_cases.sql.

Key workflows

Manage the case list

1. The left pane lists cases ordered by priority and next due date, with a search field (matches title, case number, practice area, opponent, court reference, and client name) plus status and lawyer filters.
2. "New case" opens a dialog with title, case number, status, priority, practice area, client, lawyer, court fields, opponent summary, conflict state, and description.

Work a case in the detail pane

The detail pane shows hero facts and six tabs:

1. Overview — core metadata, conflict-check panel (status unchecked/clear/possible_conflict/conflict with notes; changing the status stamps who checked and when), court panel, and linked-item counts.
2. Communication — chronological log entries with channel (email, phone, meeting, letter, portal, fax, other), direction (incoming, outgoing, internal, note), subject, summary, and participants.
3. Documents — documents linked to the case; a linkable search finds existing Dokumente to attach.
4. Tasks & dates — linked tasks plus case key dates (deadline, hearing, filing, limitation, appointment, review, other) with due date, all-day flag, status (open/done/cancelled), notes, and an optional linked calendar event.
5. Parties — people/organizations with role client, opposing_party, opposing_counsel, court, witness, expert, insurance, or other, plus contact details and notes.
6. Timeline — merged, newest-first view of communications, key dates, and entity links, filterable by group.

Link existing Clapilot records

Attach existing documents, tasks, calendar events, emails, drafts, or notes to a case; the module API resolves display labels from the source tables, and links are idempotent per (case, entity type, entity id).

How the agent can drive it

The native runtime exposes first-class Cases tools (tool family cases_, active on the Cases module page):

• cases_list — list cases with client, lawyer, deadline, conflict, and status context; filters: search, status, mandant_id, assigned_user_id, practice_area, limit (1-300).
• cases_get — read one case by id including linked parties, key dates, communications, documents, tasks, and timeline.
• cases_create — create a case; required title; optional case number, status, priority, practice area, mandant_id (client), assigned_user_id (lawyer), court fields, opponent summary, conflict status/notes, opened_at, description.
• cases_update — update case metadata, workflow status, assigned lawyer, court references, or conflict-check state by id.
• cases_delete — delete one case by id.
• cases_link_entity / cases_unlink_entity — attach or remove a document, task, calendar_event, email, draft, or note link on a case.
• cases_add_communication — add a log entry (required case_id, summary; optional channel, direction, occurred_at, subject, participants).
• cases_add_key_date — add a deadline/hearing/filing/limitation/appointment/review date (required case_id, title, due_at; optional kind, all_day, notes, calendar_event_id).

On the module page the agent is instructed to answer case questions with cases_list/cases_get instead of manually combining Mandanten, Dokumente, Aufgaben, and Kalender.

Module API reference

Base: /api/modules/cases/api

Configuration & limits

• No module settings page; behavior is fixed by the API. List page size defaults to 80 (max 300); timeline pages default to 40 (max 120); linkable search returns up to 100 rows.
• Data model (module migration bundled-modules/cases/migrations/001_cases.sql): legal_cases, legal_case_parties, legal_case_key_dates, legal_case_communications, legal_case_links. Deleting a case cascades to its parties, dates, communications, and links.
• Cases reference existing mandanten and users rows; deleting those sets the case fields to null rather than deleting the case.

Troubleshooting

• "DATABASE_URL is missing" errors: the module API needs the app database; without DATABASE_URL in the runtime environment the Cases API is disabled.
• A link shows a raw UUID as its label: the linked source record was deleted or has no title; set an explicit label on the link.