add doc that explains how to reset sync cursor

[MagnusHJensen]

Quick doc that should help how DEP sync works (We also have the general entry) and then how to reset, and a call out that it's okay to do even for larger deployments.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JordanMontgomery]

The only one caveat I would add here is that we discovered with customer-numa in the middle of a large Jamf->Fleet migration that when a customer transfers a bunch of devices in ABM, if devices hit Apple's threshold for the "cooldown"/THROTTLED state, Apple stops returning them on the sync cursor, seemingly until they're out of cooldown(e.g. 24 hours later). It also does not send "remove" events to the MDM the devices are being transferred from, during this period

That is, unless you reset the cursor and do a full fetch which returns these devices. We've asked Apple for clarification on this and we don't have any additional data. I don't think it makes it more risky but it's worth watching for as a possibility. I think Apple's refusal to return them to the normal incremental syncs is their attempt at stopping us from extending the cooldown period, but this will result in extending it. Probably only applicable if a customer says something like "yeah I just transferred a bunch of devices over and they never showed up in fleet" and logs correspond that we never got events for them

[MagnusHJensen]

Right, that makes sense do we know if they return it on the fetch-devices endpoint? Since our first run after resetting would hit that, if I understand it correctly, then after getting all devices back, we start to run the sync endpoint again?

This was mainly also just for remembering it's an option, but rarely should it be used, unless we have a bug (which this prompted) and used as a possible idea of fixing the situation.

[MagnusHJensen]

Added what you mentioned as a note

[JordanMontgomery]

They don't return those cooldown devices on our first(usually empty) call to the fetch-devices endpoint during a normal sync run. They seemingly only return them if we reset the cursor(or you upload a new ABM token to a server) and then get a new one from fetch-devices.