Connector Diagnostics

Every CMS module reports its own health to AACsearch. Diagnostics covers three distinct concerns:

1. Test connection — a manual check from the merchant's CMS admin page that the connector token, project ID and module version are wired correctly.
2. Heartbeat — a periodic keepalive so the AACsearch dashboard can label the connector online or offline.
3. Diagnostics report — a structured payload describing the module's most recent sync state, environment versions and any errors the module captured locally.

This page documents the moving parts and the retry rules every module must implement.

Test connection

Every CMS module should expose a Test connection button in its admin UI. The button calls POST /api/connectors/handshake with the configured token and platform identifier.

POST /api/connectors/handshake
Authorization: Bearer ss_connector_<token>
Content-Type: application/json

{
  "moduleVersion": "1.0.0",
  "platform": "prestashop"
}

The handshake validates four things in one round trip:

• The Authorization header is well-formed and the token prefix is ss_connector_.
• The token hash exists in SearchApiKey, has the connector_write scope, and is not revoked.
• The reported platform is a known connector identifier.
• The token's organization owns at least one active search index.

A 200 response is the only signal a merchant needs to consider the connector configured. The response includes projectId and indexSlug — the module must persist both, since every subsequent sync, delete and diagnostics call uses them in the URL path.

Decoding handshake failures

Modules should never echo the raw error body to the merchant. Map the typed code to a human message in the local language file.

Heartbeat

Once handshake succeeds, the module should call the heartbeat endpoint every five minutes from a background task (cron, PHP scheduled task, or platform agent).

POST /api/connectors/:connectorId/heartbeat
Authorization: Bearer ss_connector_<token>

The dashboard derives connector status from SearchApiKey.lastUsedAt:

A missing heartbeat is not an error by itself — the module is just offline. Merchants typically discover offline connectors when their search index goes stale; a healthy heartbeat schedule avoids that conversation.

Diagnostics report

The richer POST /api/projects/:projectId/diagnostics call is for state that the merchant or support team can act on. Send a diagnostics report after every full sync, after a delta-sync failure, and on a daily timer regardless of activity.

{
  "moduleVersion": "1.2.3",
  "lastFullSync": "2025-01-15T09:00:00.000Z",
  "lastDeltaSync": "2025-01-15T09:55:00.000Z",
  "totalProducts": 4823,
  "phpVersion": "8.2.0",
  "shopUrl": "https://myshop.example.com",
  "errors": [
    {
      "code": "export_timeout",
      "message": "Product export timed out after 30s",
      "timestamp": "2025-01-15T09:54:30.000Z"
    }
  ]
}

What to send in errors

Send only errors the merchant can resolve or that support engineers need to triage. Useful examples:

• export_timeout — a single product mapper exceeded the script time limit
• memory_limit_reached — PHP / Node ran out of memory mid-batch
• invalid_field_mapping — a configured field is not present on the entity
• webhook_signature_mismatch — incoming webhook from the platform failed HMAC verification
• db_query_failed — a catalog query inside the module errored

Do not send transient HTTP errors that the retry loop already handles; the AACsearch side will see retry storms in its own logs.

Polling sync jobs

The full and delta sync endpoints return a jobId. Poll the job state with:

GET /api/projects/:projectId/sync/jobs/:jobId
Authorization: Bearer ss_connector_<token>

Job status transitions: running → completed or running → failed. The response includes per-step event lines and an itemsCount / failuresCount summary. Modules should poll at most once every 5 seconds and stop polling after 30 seconds with no transition. The dashboard offers the same view from Connectors → Sync history.

Job records are kept in memory (last 50 jobs per server instance) and disappear after restart. A 404 on poll is not a sync failure — modules should treat it as "status unknown" and rely on the next full or delta sync to reconcile.

Retry behavior

The Connector API enqueues writes asynchronously. A 200 response means "buffered for indexing," not "indexed." Modules need a retry strategy for the gap between the two.

When to retry

• Network errors and 5xx responses → retry with exponential backoff, capped at 5 minutes between attempts.
• sync_failed (502) → retry, backoff capped at 5 minutes.
• delete_failed (502) → retry, capped at 5 minutes.
• 4xx other than the auth codes → do not retry. Surface the error to the merchant.

When not to retry

• invalid_or_revoked_key (403) → token is dead; alert the merchant.
• invalid_input (400) → fix the payload before the next call; retrying with the same body just multiplies log noise.
• project_not_found (404) → the token does not match the configured project; alert the merchant.

Suggested backoff schedule

Cap total retry duration per job at 30 minutes. After that, log the failure, send a diagnostics report, and let the next scheduled full sync reconcile the index.

Connector status in the dashboard

From the AACsearch dashboard:

• Connectors → list view — shows each connector token with its heartbeat status, last sync timestamp and total product count derived from the last diagnostics report.
• Connectors → sync history — pulls from the in-memory job store. Filter by full / delta / delete and by status.
• Connectors → diagnostics — last diagnostics payload received per connector, including environment versions and the errors array.

A connector that has never run handshake will not appear in the list — the row is created only on the first successful handshake call.

Related pages

• Connector API Lifecycle — endpoint reference and error codes
• Connectors Overview — token model and architecture
• Custom Connector — building your own integration