Developer guide

REST, CSV, webhooks, SSO, and optional providers

Exchange assessment context and approved outcomes with stable identities, validation, idempotency, audit logs, and safe network boundaries.

MaintainerIntegratorReviewer

Assessment integration flow. External IDs enter through validated runs; only finalized results leave through controlled exports.

Responsibility

Integrations complement the assessment domain. They synchronize the minimum roster or outcome context required and return approved results; they do not turn ExamNova into the master school system or LMS.

Components and data flow

Inbound REST and CSV runs identify records by source_system and stable external_id.
Validation produces accepted, skipped, conflict, and row-error outcomes before or during commit.
Idempotency keys prevent duplicate runs and webhook replay.
Outbound result exports read finalized, published state and record delivery status.
SSO validates issuer, audience, signature, time claims, nonce/state, and mapped membership.
Optional AI/communication providers use guarded URLs, explicit configuration, limits, and recorded outcomes.

Rules that must remain true

External identities are stable and tenant-scoped.
Conflicts are reported rather than silently overwriting local assessment facts.
Tokens and secrets are write-only/masked and transmitted only over approved HTTPS endpoints.
Webhook signatures and timestamps are verified before parsing trusted meaning.
Optional provider failure cannot corrupt the primary workflow transaction.

Failure modes

Email as an external primary key creates accidental duplicates.
Unbounded CSV processing exhausts memory or request time.
Retrying a result export without idempotency duplicates downstream records.
SSO domain matching without claim validation admits the wrong identity.

Safe extension guidance

Version payloads and document required/optional fields, error shapes, pagination, and limits.
Use background jobs for large runs and expose auditable progress.
Add provider-specific adapters behind a stable internal contract.
Document timeout, retry, backoff, circuit, and manual recovery behavior.

Required tests

Duplicate REST/CSV runs are idempotent and report stable row outcomes.
Cross-tenant external IDs cannot resolve records.
Signed webhook success, invalid signature, stale timestamp, replay, and retry.
SSO issuer/audience/nonce/time/domain failures.
Provider timeout and malformed response leave the primary record consistent.

Release gate: Publish an integration only with a documented contract, sample safe payloads, scopes, idempotency, errors, audit behavior, and adversarial tests.