feat(users): preserve handles and role assignments via v1

[michael-richey]

What

Preserve distinct user handles during sync by mapping users by exact-case handle and optionally creating them through the v1 user API. Reconcile role assignments after creation and on later retries without reporting partial results as full success.

Why

Email is not necessarily unique, but the v2 create endpoint derives the destination handle from email. Distinct source users that share an email can therefore collide on one destination handle. The v1 endpoint accepts an explicit handle.

Role assignment is a separate API operation. A user can be created or updated successfully while one or more role assignments fail, so those partial outcomes must remain retryable and observable.

Changes

• Map users by attributes.handle instead of email, preserving exact case.
• Keep handle out of v2 create and update payloads and exclude it from update diffs.
• Add the opt-in --use-v1-user-api flag and DD_USE_V1_USER_API environment variable; both default off.
• Create flagged users through POST /api/v1/user, then resolve the v2 UUID by exact-case handle for destination state and downstream references.
• Assign only missing mapped roles after v1 creation and during later updates.
• Continue attempting remaining roles after an assignment fails.
• Persist the reconciled user, successful role assignments, and successful attribute updates before raising a structured partial failure.
• Route partial role failures through the existing failed-resource counter, failure event, and failure metric instead of emitting success.
• Document the flag in the README.

Compatibility

With the flag disabled, user creation continues to use v2. Existing destination state produced by earlier handle collisions is not rewritten automatically; affected state must be cleaned before enabling the v1 path.

Tests

• Exact-case handle mapping and shared-email users.
• v1 and v2 create paths, payload filtering, UUID reconciliation, and update behavior.
• Existing and missing role assignments.
• Partial role failure during initial creation.
• Second-run role retry with later roles still attempted, successful state persisted, and a structured failure raised.
• Flag configuration and CLI parsing for sync and migrate.

[Copilot]

Pull request overview

Adds an opt-in v1 user-creation path to preserve exact-case user handles (avoiding shared-email collisions), switches user mapping to be handle-based, and makes role reconciliation retryable/observable via structured partial failures.

Changes:

• Map existing/users-by-handle (attributes.handle) and exclude handle from v2 create/update payloads and diffs.
• Add --use-v1-user-api / DD_USE_V1_USER_API to create users via POST /api/v1/user, then reconcile the v2 UUID by exact-case handle.
• Reconcile only missing role assignments, continue after per-role failures, persist partial state, and raise a structured UserRoleAssignmentError.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
datadog_sync/model/users.py	Handle-based mapping, optional v1 create flow, role reconciliation + partial failure error type, v2 payload filtering/diff exclusion.
datadog_sync/utils/configuration.py	Adds use_v1_user_api to configuration and wiring from CLI kwargs.
datadog_sync/commands/shared/options.py	Introduces --use-v1-user-api CLI option + env var support.
datadog_sync/constants.py	Adds DD_USE_V1_USER_API constant.
README.md	Documents the v1 user creation flag and the shared-email handle-collision rationale.
tests/unit/test_users.py	New unit tests covering handle mapping, v1/v2 create paths, UUID reconciliation, role assignment behavior, and flag wiring.

---

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