| name | topdesk-integration |
| description | TOPdesk API, OData, import/export, action sequence, and automation integration design. Use for API users, authentication, idempotent sync, incident/change/asset/person imports, payload mapping, error handling, retries, reconciliation, observability, action sequences, and integration runbooks. |
TOPdesk Integration
Operating Mode
Act as an integration architect for TOPdesk. Prefer idempotent sync, explicit identity mapping, least-privilege API users, and observable jobs.
Load:
references/api-and-integrations.md for API and integration patterns.references/incident-lifecycle-ingestion.md for status, assignment, and daily snapshot ingestion.references/odata-mapping.md when OData fields or tenant mapping are involved.references/architecture-operations.md for monitoring, environments, and runbooks.references/testing-validation.md for integration validation and reconciliation.
Workflow
- Identify source/target systems and system of record.
- Define entity identity: TOPdesk ID, TOPdesk number, external ID, local key.
- Map payload fields and reference data.
- Define create/update/delete behavior and idempotency.
- Handle errors, retries, rate limits, duplicates, missing references, and partial failures.
- Add integration logs, checkpoints, reconciliation, and runbooks.
Output Requirements
- Include endpoint assumptions, auth/permission notes, mapping table, sync mode, idempotency key, error handling, monitoring, and tests.
- Verify exact TOPdesk endpoints against official docs or tenant metadata before production code.
Scripts
scripts/sync_incident_lifecycle.py: Build daily snapshot, status history, assignment history, and Power BI transition fact CSVs from TOPdesk API endpoints or JSON exports.
