From e95693d684076ef87c436840caf2c5aa4581456d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 23:36:13 +0000 Subject: [PATCH] docs(routing): add routing rules documentation to API.md and UserGuide.md Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> --- docs/API.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++ docs/UserGuide.md | 47 ++++++++++++++ 2 files changed, 201 insertions(+) diff --git a/docs/API.md b/docs/API.md index d5a0bf40..779f216a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1960,6 +1960,160 @@ Pass no `pipeline_id` query parameter (or omit it) to clear the assignment. ``` +## Routing Rules + +Routing rules let you conditionally assign documents to different pipelines +based on file properties such as type, size, filename, or AI-extracted +metadata. Rules are evaluated in **position order** (lowest first); the first +rule that matches wins. If no rule matches, the system falls back to the +owner's (or global) default pipeline. + +### Supported operators and fields + +```bash +GET /api/routing-rules/operators +``` + +Returns the catalogue of valid operators and built-in fields so UIs can +populate dropdowns without hard-coding values. + +**Response (200):** +```json +{ + "operators": ["contains", "equals", "gt", "gte", "lt", "lte", "not_contains", "not_equals", "regex"], + "builtin_fields": ["category", "document_type", "file_type", "filename", "size"], + "metadata_prefix": "metadata." +} +``` + +> **Tip:** For AI metadata fields use the `metadata.` prefix, e.g. +> `metadata.sender`, `metadata.amount`. + +### List routing rules + +```bash +GET /api/routing-rules +``` + +Returns the current user's rules **plus** any system-wide rules +(`owner_id = null`), ordered by position. + +**Response (200):** +```json +[ + { + "id": 1, + "owner_id": "alice", + "name": "Route invoices", + "position": 0, + "field": "document_type", + "operator": "equals", + "value": "Invoice", + "target_pipeline_id": 3, + "is_active": true, + "created_at": "2026-03-09T12:00:00+00:00", + "updated_at": "2026-03-09T12:00:00+00:00" + } +] +``` + +### Create routing rule + +```bash +POST /api/routing-rules +Content-Type: application/json + +{ + "name": "Route invoices", + "field": "document_type", + "operator": "equals", + "value": "Invoice", + "target_pipeline_id": 3 +} +``` + +Optional fields: `position` (auto-assigned if omitted), `is_active` (default `true`). + +**Response (201 Created):** The created rule object. + +### Get routing rule + +```bash +GET /api/routing-rules/{rule_id} +``` + +**Response (200):** A single rule object. + +### Update routing rule + +```bash +PUT /api/routing-rules/{rule_id} +Content-Type: application/json + +{ "name": "Renamed rule", "operator": "contains", "is_active": false } +``` + +Only the supplied fields are updated. + +**Response (200):** The updated rule object. + +### Delete routing rule + +```bash +DELETE /api/routing-rules/{rule_id} +``` + +Returns **204 No Content**. + +### Reorder routing rules + +```bash +PUT /api/routing-rules/reorder +Content-Type: application/json + +{ "rule_ids": [3, 1, 2] } +``` + +Provide the complete ordered list of your rule IDs. Positions are reassigned +0, 1, 2, … in the given order. + +### Evaluate rules (dry run) + +```bash +POST /api/routing-rules/evaluate +Content-Type: application/json + +{ + "file_type": "application/pdf", + "filename": "invoice_2024.pdf", + "size": 204800, + "document_type": "Invoice", + "metadata": { "sender": "Acme Corp" } +} +``` + +Tests which rule (if any) would match the given properties **without** +actually routing a document. + +**Response (200) – match found:** +```json +{ + "matched": true, + "rule": { "id": 1, "name": "Route invoices", "..." : "..." }, + "target_pipeline": { "id": 3, "name": "Invoice Pipeline", "is_active": true } +} +``` + +**Response (200) – no match:** +```json +{ + "matched": false, + "rule": null, + "target_pipeline": null +} +``` + + ## API Tokens Personal API tokens allow programmatic access to the DocuElevate API without diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 9906a89c..20f256c5 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -626,6 +626,53 @@ Pass no `pipeline_id` to clear the assignment and fall back to the system defaul Admins can create **system pipelines** that appear in every user's pipeline list. These can be set as the global default so all users benefit from a consistent processing baseline. Navigate to **Pipelines** and check the **System pipeline** box when creating a new one (admin only). +### Conditional routing rules + +Routing rules automatically assign incoming documents to the right pipeline +based on their properties — no manual pipeline selection required. + +**How it works:** + +1. Define one or more routing rules via the API + (`POST /api/routing-rules`). +2. Each rule specifies a **field** to inspect, an **operator** (condition), + a **value** to compare against, and a **target pipeline**. +3. When a document is processed, rules are evaluated **in position order** + (lowest first). The first matching rule wins and the document is routed + to that pipeline. +4. If no rule matches, the document is processed by the default pipeline. + +**Available fields:** + +| Field | Description | +|-------|-------------| +| `file_type` | MIME type, e.g. `application/pdf` | +| `filename` | Original filename | +| `size` | File size in bytes | +| `document_type` | AI-classified type (Invoice, Contract, …) | +| `category` | Alias for `document_type` | +| `metadata.` | Any key from the AI-extracted metadata JSON | + +**Available operators:** + +| Operator | Description | +|----------|-------------| +| `equals` / `not_equals` | Exact match (case-insensitive) | +| `contains` / `not_contains` | Substring match (case-insensitive) | +| `regex` | Full Python regex match (case-insensitive) | +| `gt` / `lt` / `gte` / `lte` | Numeric comparison (greater/less than) | + +**Example:** Route all invoices over 1 MB to a dedicated pipeline: + +``` +Rule 1: field=document_type, operator=equals, value=Invoice, target_pipeline=3 +Rule 2: field=size, operator=gt, value=1048576, target_pipeline=5 +``` + +You can test your rules without actually routing a document using the +**evaluate** endpoint (`POST /api/routing-rules/evaluate`). For the full +API reference, see [API Documentation](API.md#routing-rules). + ## API Access For programmatic access, DocuElevate provides a comprehensive REST API: