Skip to main content
Restricted Access: This documentation is only accessible to @tenzo.ai and @salv.ai email addresses.

​
Overview

ATS Sync Controls let support users with full access enable or disable per-type ATS sync and adjust sync cursors (last-synced timestamps) while impersonating an org. Controls live in the regular app under Admin Settings → ATS Integrations → Health Monitor, in Org View only. Supported sync types: Tearsheets, placements and notes also keep cursors (tearsheets_last_synced_at, placements_last_synced_at, notes_last_synced_at) but have no toggle or lookback control in the UI.

​
How the cursor advances

Setting a cursor here only chooses where the next cycle starts. Whether a cycle then moves the cursor forward is decided by a single rule shared by all sync types: the cursor is held whenever the window was not fully enumerated or any retryable failure occurred, and it is advanced when the window was empty, everything succeeded, or the only failures were permanent per-item failures in queue mode, which are recorded and skipped rather than retried from the cursor. The cursor moves to the sync start time, never the end time. The full table is in ATS Sync Alerts.

​
Access requirements

  • User must be a support user with full access enabled (auth.is_full_access).
  • User must be impersonating the target org. Endpoints scope changes to auth.org_id; integrations belonging to other orgs return 403.
  • Sync controls are hidden in Global View on the Health Monitor. Switch to Org View to see them.

​
UI behavior

Each sync type shows:
  • A toggle (Enabled / Disabled) with a confirmation modal.
  • Lookback preset buttons: Now, 1 day, 2 days, 1 week, 1 month.

​
Enable

When enabling sync, the UI shows a confirmation modal with a lookback selector. If the user selects a lookback preset in the enable modal, that preset is applied even when the cursor is fresh.

​
Disable

Disabling sync only flips the toggle. The last-synced timestamp is never changed.

​
Standalone lookback

Lookback buttons update the cursor without changing the enable/disable state. Each click opens a confirmation modal.

​
API endpoints

Lookback presets map to: NOW (0 days), ONE_DAY, TWO_DAYS, ONE_WEEK, ONE_MONTH (30 days). Maximum lookback is 30 days. When enabling with a stale cursor, the API may return a warning string indicating the old timestamp will not be used.

​
Cursor resolution logic

Pure logic lives in server/ats/sync_control_logic.py:
  • Disable → no cursor change.
  • Enable + explicit lookback → cursor = now - lookback; stale warning if prior cursor was stale.
  • Enable + null cursor → cursor = now.
  • Enable + stale cursor, no lookback → cursor = now + stale warning.
  • Enable + fresh cursor, no lookback → cursor unchanged.

​
Testing

​
Automated tests

  • test_sync_control_logic.py — 20 unit tests for cursor classification and enable/lookback resolution.
  • test_ats_sync_controls_api.py — 8 unit tests for full-access auth, org scoping, and DB side effects.

​
Manual E2E verification

Verified locally against Docker Postgres (salv-postgres-dev, database salv_local) and the Health Monitor UI at /settings/ats_integrations/ats_health in Org View with full-access impersonation. Test integration: recruitcrm:433964ef-2d90-4d91-810c-62ee716ded3d After each action, the Health Monitor UI refreshed to show updated toggle labels and last-synced timestamps.

​
Edge cases covered

  • Null cursor on enable defaults to now.
  • Stale cursor (> 30 days) warns and defaults to now unless a lookback is chosen.
  • Fresh cursor is preserved on enable when lookback is Now.
  • Explicit lookback on enable or via standalone buttons updates cursor independently of toggle state.
  • Disable never mutates cursor columns.
  • Org scoping and full-access gating enforced at the API layer (unit tested).