# Example: Catalog & Sync

> A playbook for integration and data-sync tickets, the category where the root cause is usually an expired credential.

Source: https://triagic.com/docs/playbooks/catalog-and-sync

Products, inventory or orders that are not flowing between your platform and something
external. Almost always a credential, a rate limit, or a worker that died, which
makes it a good example of a playbook whose value is mostly in the *ordered checklist*.

## Fields [#fields]

**Name**

```
Catalog & Sync
```

**Description**

```
Tickets about data not syncing between the platform and an external system: product
catalog imports, inventory counts, order exports, and connected-store integrations
that have stopped updating.
```

**Routing hints**

```
sync, "not syncing", "products missing", "0 items", catalog, import, export,
inventory, "stock not updating", "connection lost", reconnect, "stuck at", OAuth,
"reauthorize", integration disconnected
```

**Triage instructions**

```
A sync that reports zero items is almost never an empty catalog. It is a broken
connection reporting success. Start from that assumption.

Check in this order:

1. MongoDB: the merchant's integration/connection document. Look at the token expiry
   and the last successful sync timestamp. An expired OAuth token is the single most
   common cause in this category by a wide margin.
2. The sync run records for this merchant: did runs happen, and what did they report?
   A run that completed with 0 items is different from no run at all, and points at a
   different cause.
3. app-sync-* OpenSearch logs for this merchant_id around the last attempted run.
   Look for 401/403 from the external provider and for rate-limit responses.
4. Sentry for exceptions from the sync worker in the same window.
5. Kubernetes: the state of the sync-service deployment. CrashLoopBackOff explains
   every merchant's sync stopping at once and should be checked before concluding
   anything merchant-specific if the failure is broad.

Known causes, most to least common:
- expired or revoked OAuth token — merchant must reconnect the integration
- external provider rate limiting, visible as 429s in the sync logs
- sync worker crashed or is in CrashLoopBackOff, affecting everyone
- a schema change on the external side breaking the mapping for a specific field
- the merchant genuinely has no products in the source

Conclusions:
- Establish scope before cause: check whether other merchants synced successfully in
  the same window. A token problem is one merchant; a worker problem is all of them.
- If the token expired, say so and state that the merchant must reconnect. Do not
  describe it as a platform outage.
- If the sync worker is unhealthy, this stops being a support ticket — say so
  explicitly and name the deployment.
```

**Data sources**

```
org-mongodb, org-opensearch, org-sentry, org-kubernetes
```

**Visibility**

Everyone in the organization.

## Why it is scoped this way [#why-it-is-scoped-this-way]

Connection state lives in MongoDB, sync attempts in OpenSearch, worker exceptions in
Sentry. Kubernetes is included for one specific reason: sync failures are the category
most likely to be caused by a dead worker, and being able to see
`CrashLoopBackOff` turns a long merchant-by-merchant investigation into a
one-tool-call answer.

Payments systems are excluded. A catalog sync problem is never in the payments
database, and letting the agent look there is pure cost.

## Tuning it [#tuning-it]

If your integrations are with a small number of named external platforms, add their
names to the routing hints. Customers name the platform, not the word "sync", and
that's what makes classification land.