Workspace Connector Sync Log - Well Starter Kit

WorkspaceConnectorSyncLog is an append-style audit record that captures the lifecycle of a single connector sync run for a workspace. It is created when a sync begins (SCHEDULED or IN_PROGRESS), updated by the sync orchestrator as the run progresses, and finalised with SUCCESS or ERROR once the connector returns or fails. Every log row belongs to exactly one WorkspaceConnector and one Workspace, providing a per-connector execution history that the platform uses for observability, retry logic, and connector-status dashboards.

Naming	Value
Object	Workspace Connector Sync Log
Resource type (JSON:API `type`)	`workspace_connector_sync_log`
Collection / records root	`workspace_connector_sync_logs`
REST base	`/v1/workspace-connector-sync-logs`
Entity class	`WorkspaceConnectorSyncLog`

API operations

Operation	Method & path	Status
List	`GET /v1/workspace-connector-sync-logs`	✅ Implemented
Retrieve	`GET /v1/workspace-connector-sync-logs/{id}`	✅ Implemented
Create	`POST /v1/workspace-connector-sync-logs`	🟡 Planned
Update	`PATCH /v1/workspace-connector-sync-logs/{id}`	🟡 Planned
Delete	`DELETE /v1/workspace-connector-sync-logs/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
workspace_connector_sync_log_id	string, UUID, 🔒 system	✅ Yes	unique; generated by gen_random_uuid() at INSERT	—	Public stable identifier for this sync log row. Used in all API responses; the internal pk is never exposed.
status	string (ConnectorSyncStatusEnum)	✅ Yes	DEFAULT ‘scheduled’; non-nullable; one of the four enum values	scheduled, in_progress, success, error	Current execution state of the sync run. Starts as SCHEDULED (or IN_PROGRESS when created by the service), transitions to SUCCESS or ERROR once the connector run completes. The sync orchestrator is the only writer.
trigger_type	string (SyncTriggerTypeEnum), nullable	⚪ No	nullable; one of the three enum values when present	cloud_task, manual, oauth_callback	How the sync run was initiated. CLOUD_TASK = scheduled Cloud Tasks queue; MANUAL = user-initiated via UI or API; OAUTH_CALLBACK = triggered immediately after a successful OAuth authorization flow.
cloud_task_id	string, VARCHAR(255), nullable	⚪ No	nullable; max 255 chars (cast from TEXT in Migration20260407100000)	—	The fully-qualified Cloud Tasks task name associated with this sync run when trigger_type is CLOUD_TASK. Null for manual and OAuth-callback triggers. Used for deduplication and traceability in the task queue.
started_at	datetime, nullable	⚪ No	nullable; set by the orchestrator when actual processing begins (not at row creation for SCHEDULED status)	—	Timestamp when the sync run transitioned from SCHEDULED to IN_PROGRESS and connector API calls began. Null if the run was never picked up (e.g. task enqueued but not yet dispatched).
completed_at	datetime, nullable	⚪ No	nullable; set atomically with duration_ms and the terminal status (SUCCESS or ERROR)	—	Timestamp when the sync run reached a terminal state. Null while the run is SCHEDULED or IN_PROGRESS.
duration_ms	integer, nullable	⚪ No	nullable; integer; computed as completed_at - started_at in milliseconds by the repository markSuccess/markError helpers	—	Wall-clock duration of the sync run in milliseconds. Null when started_at is null (run never began) or while still in progress. Derived at finalisation time, not stored as a trigger.
error	string, TEXT, nullable	⚪ No	nullable; no length limit; populated only when status = error	—	Human-readable error message or stringified exception captured when the sync run terminates with an ERROR status. Null on success. Used by the monitoring layer and displayed in the connector-status dashboard.
metadata	jsonb, nullable	⚪ No	nullable; free-form JSONB object; no fixed schema enforced at the DB level	—	Provider-specific sync context written at completion. Common keys include records_synced, pages_fetched, connector_slug, and billing-related counts. Not queried by the platform for logic — observability and debugging only.
created_at	datetime, 🔒 system	✅ Yes	set once on INSERT via MikroORM onCreate lifecycle hook; never updated	—	Row creation timestamp. Corresponds to when the sync was enqueued or initiated, which may precede started_at by a few seconds for CLOUD_TASK triggers.
updated_at	datetime, 🔒 system	✅ Yes	set on INSERT and on every UPDATE via MikroORM onCreate/onUpdate lifecycle hooks	—	Last modification timestamp. Advances each time the sync orchestrator patches status, started_at, completed_at, duration_ms, error, or metadata.
deleted_at	datetime, nullable	⚪ No	nullable; soft-delete convention; all queries must filter deleted_at IS NULL	—	Soft-delete timestamp. Null for active log rows. When set, the log is logically removed but retained for audit purposes.

Relationships

Name	Type	Required	Description
workspaceConnector	to-one (workspace_connector)	✅ Yes	The WorkspaceConnector instance this sync run belongs to. Every sync log is scoped to exactly one connector. Cascade-delete: when the parent WorkspaceConnector is deleted, all its sync logs are deleted via ON DELETE CASCADE.
workspace	to-one (workspace)	✅ Yes	The Workspace that owns this sync log. Denormalized from the WorkspaceConnector for efficient tenant-scoped queries (direct workspace_pk filter without joining through workspace_connectors). Cascade-delete: when the Workspace is deleted, all its sync logs are deleted via ON DELETE CASCADE.

System-computed

workspace_connector_sync_log_id is generated by gen_random_uuid() at INSERT (PostgreSQL DEFAULT); the column carries a UNIQUE constraint.
created_at is set once by MikroORM onCreate: () => new Date() and never mutated.
updated_at is set by both onCreate and onUpdate hooks, advancing on every PATCH by the sync orchestrator.
deleted_at follows the platform-wide soft-delete convention; active rows have deleted_at = NULL; all repository and data-view queries must include this filter.
duration_ms is computed at finalisation time by the repository helpers (markSuccess / markError) as completed_at.getTime() - started_at.getTime(). It is null when started_at is null.
The workspace FK is denormalized from WorkspaceConnector.workspace at row creation time, enabling workspace-scoped index queries (idx_workspace_connector_sync_logs_workspace) without a join.
Three indexes support the common access patterns: composite (workspace_connector_pk, created_at DESC) for per-connector history paging; (workspace_pk) for workspace-scoped listing; (status) for filtering by sync state. None carry a WHERE predicate — they are plain B-tree indexes, not partial indexes.
The workspace_connector_service_id column that was present in the original migration was dropped in Migration20260407100000 and is absent from the current entity — do not reference it.
cloud_task_id was narrowed from TEXT to VARCHAR(255) in Migration20260407100000.

Example

{
  "data": {
    "type": "workspace_connector_sync_log",
    "id": "f3a1bc44-902c-4f8d-b7e2-0d9e5a2c1340",
    "attributes": {
      "workspace_connector_sync_log_id": "f3a1bc44-902c-4f8d-b7e2-0d9e5a2c1340",
      "status": "success",
      "trigger_type": "cloud_task",
      "cloud_task_id": "projects/well-prod/locations/europe-west1/queues/connector-sync/tasks/task-7f3b91c2",
      "started_at": "2026-06-02T08:14:02.000Z",
      "completed_at": "2026-06-02T08:14:47.000Z",
      "duration_ms": 45000,
      "error": null,
      "metadata": {
        "records_synced": 312,
        "pages_fetched": 4,
        "connector_slug": "pennylane"
      },
      "created_at": "2026-06-02T08:14:01.800Z",
      "updated_at": "2026-06-02T08:14:47.200Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace_connector": {
        "data": { "type": "workspace_connector", "id": "a9d3c82e-1f45-4b2c-8e67-3d0a1b9c4512" }
      },
      "workspace": {
        "data": { "type": "workspace", "id": "c1e7f034-87b2-41d3-9a56-0f2e8b7d3c90" }
      }
    }
  }
}

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

Documentation Index

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example