ConnectorFilter

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"
    }
  }
}

_{Source: apps/api/src/database/entities/ConnectorFilter.ts · domain: ingestion · tier: Infrastructure}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example