Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
ConnectorFilter defines the document-routing rules applied to output connectors during sync orchestration. Each row is either a template filter (template=true, workspace=null — a platform-managed default shared across all workspaces for a given connector type) or a custom filter (template=false, workspace scoped — workspace-specific overrides). The config column carries a Hasura WHERE-clause JSONB predicate that gates which documents flow to the target connector, while natural_language provides a human-readable description for display in the workflow editor. ConnectorFilters are written exclusively by the seed pipeline (mikro:seed:connector-filters command and its migration equivalent) and surfaced read-only via the workspace-connectors JSON:API as a sideloaded included resource.
| Naming | Value |
|---|
| Object | ConnectorFilter |
Resource type (JSON:API type) | connector_filter |
| Collection / records root | — (not a records root) |
| REST base | /v1/connector-filters |
| Entity class | ConnectorFilter |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/connector-filters | 🟡 Planned |
| Retrieve | GET /v1/connector-filters/{id} | 🟡 Planned |
| Create | POST /v1/connector-filters | 🟡 Planned |
| Update | PATCH /v1/connector-filters/{id} | 🟡 Planned |
| Delete | DELETE /v1/connector-filters/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| connector_filter_id | string (UUID) | ✅ Yes | unique | Any valid UUID v4 | Public stable identifier for this filter. Generated by gen_random_uuid() on insert. Used as the JSON:API id field. |
| template | boolean | ✅ Yes | default false | true | false | Discriminator for filter kind. true = platform-managed template filter (workspace=null, shared across all workspaces for the connector type). false = workspace-specific custom filter. |
| config | object (JSONB) | ✅ Yes | NOT NULL; no fixed schema — shape is dynamic per connector | Any valid Hasura WHERE clause JSON object, e.g. { “document_type”: { “_in”: [“380”, “381”] } } | Filter predicate expressed as a Hasura WHERE-clause JSONB object. Gates which documents are routed to the output connector during sync. Shape mirrors Hasura boolean expression syntax (field → operator → value). |
| natural_language | string (text) | ✅ Yes | NOT NULL; no length limit (text column) | Free text | Human-readable description of what the filter does. Displayed in the workflow editor as the suggested default rule copy for the output connector. |
| created_at | 🔒 system — datetime | ✅ Yes | timestamptz(6); NOT NULL | ISO 8601 UTC datetime | Timestamp set automatically on row creation via MikroORM onCreate hook. Never updated after insert. |
| updated_at | 🔒 system — datetime | ⚪ No | timestamptz(6); nullable | ISO 8601 UTC datetime or null | Timestamp refreshed automatically on every row update via MikroORM onUpdate hook. NULL until the first update. |
| deleted_at | 🔒 system — datetime | ⚪ No | timestamptz(6); nullable | ISO 8601 UTC datetime or null | Soft-delete timestamp. NULL means the filter is active. When set, the filter is excluded from all sync queries. Set by the seed pipeline on logical removal. |
Relationships
| Name | Type | Required | Description |
|---|
| connector | to-one (ManyToOne) | Yes — NOT NULL FK | The Connector (provider definition) this filter is attached to. The connector FK is non-nullable and cascades on update. One connector may have at most one template filter (identity = connector_pk + template=true + workspace=null + deleted_at=null per seed idempotency contract) and any number of custom workspace filters. |
| workspace | to-one (ManyToOne, nullable) | No — nullable FK (ON DELETE SET NULL) | The Workspace this custom filter belongs to. NULL for template filters (template=true). Set for workspace-specific custom filters (template=false). The FK cascades on update and sets null on workspace deletion. |
System-computed
- connector_filter_id — generated by gen_random_uuid() database default on INSERT; unique constraint ensures no collision
- created_at — set by MikroORM onCreate: () => new Date() hook; never modified after creation
- updated_at — set by both MikroORM onCreate and onUpdate hooks; reflects last modification time by the seed/migration pipeline
- deleted_at — soft-delete sentinel; set by the seed pipeline (syncConnectorFilters) when a filter is logically removed; never modified by user API calls
- Template filter identity — the seed pipeline enforces a one-template-per-output-connector invariant: identity = (connector.pk, template=true, workspace=null, deleted_at=null); subsequent seed runs update config and natural_language in place rather than inserting duplicates
- Indexes — idx_connector_filters_workspace_deleted (workspace, deleted_at) for Hasura permission filter hot path; idx_connector_filters_connector_workspace (connector, workspace, template) for sync orchestration lookup; both created by Migration20260416000000_hasura_and_service_hot_path_indexes_round4
Example
{
"data": {
"type": "connector_filter",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"template": true,
"config": {
"document_type": {
"_in": ["380", "381", "383", "384", "325", "326", "385", "386"]
}
},
"natural_language": "Routes invoices, credit notes, and debit notes (UN/CEFACT document type codes 380, 381, 383, 384, 325, 326, 385, 386).",
"created_at": "2025-12-02T19:26:37.000Z",
"updated_at": "2026-04-14T16:00:00.000Z"
}
}
}
apps/api/src/database/entities/ConnectorFilter.ts · domain: ingestion · tier: Infrastructure
