Event Participant Import Functional Requirements

Upload endpoint: PUT /api/event-participants/import

Results endpoint: GET /api/event-participants/import/{jobId}

Only the named sheet is processed (multi-sheet workbooks are supported)

The header row (row 0) is used to detect column positions; data starts at row 1

Blank rows (first five cells empty) are skipped silently

Each logical column has one or more aliases (e.g. FirstName, First Name, FN, Name all map to FIRST_NAME)

Header matching ignores case and whitespace

Missing non-required columns default to null (or the column-specific default)

Unknown columns are ignored with a log entry

Required columns (FIRST_NAME, LAST_NAME) must be present or the import fails early with a 400-class error

A row’s registrationId column (also accepted as RegistrationID, ExternalID, ExternalEPID) is matched against EventParticipant.registrationId scoped to the target event

A match produces an UPDATED outcome; no match produces a CREATED outcome

Re-running the same import against the same event does not produce duplicates

Re-running does not inflate totalRows count or churn EventParticipant.id

Identity number (ID_NUMBER + ID_TYPE + ID_COUNTRY) is the strongest match signal

Where no identity number is available, (FIRST_NAME + LAST_NAME + DOB) is attempted

Email is used as a secondary signal but not sole match criterion

An unambiguous match reuses the existing Person; an ambiguous match produces a WARNING outcome for operator review

A successful match on an existing Person still results in an EP CREATED outcome if no EP exists for that Person in the event

Query parameters createCustom1, createCustom2, createCustom3 control auto-creation per custom-list column (default: true)

When the flag is true, a missing value is created as a new CustomListValue on the corresponding CustomList and linked to the row

When the flag is false, a missing value produces a WARNING outcome and the EP is still created/updated without the custom value

Null-safe: a blank custom-list cell is not an error (the EP simply has no custom value for that column)

NUMBER alias matches Bib, BibNumber, RaceNumber, No

The number is resolved within the event’s NumberType stock

Empty / absent cell: the EP’s existing number_id (if any) is preserved. Imports never clear a race-number assignment — clearing is an explicit admin action outside the import path.

Populated cell, EP has no number: the resolved number is assigned (IN_STOCK → ISSUED) and a IMPORT_EP row is written to race_number_state_log.

Populated cell, EP already has the same number: idempotent no-op (no state change, no log row).

Populated cell, EP already has a different number: the import treats this as a number swap. RaceNumberAssignmentServiceEx.recordNumberAssignment(…​, REASSIGNED, …​) fires on the originating EP, and — per Feature #473 / US #505 — the participant’s future same-type EPs receive a DETACHED row and their number_id is cleared for later reconciliation. The import response records the swap for operator visibility. Opt-out is not available from the import path; to do a one-event-only swap, use the dedicated reassignment endpoint with temporary = true after the import.

Unresolvable reference: a NUMBER_ID or NUMBER that does not resolve (not found, ambiguous, wrong state) produces a WARNING and the EP is created/updated without the number.

The assignment goes through RaceNumberAssignmentServiceEx so that history and validation are preserved.

A missing NUMBER cell is never an error.

A blank / absent order block is permitted — the EP is created without order association (no NPE)

Default ORDER_STATUS is P (Pending) when the column is absent

Re-import of the same row does not create duplicate order line items for the EP

Outcome values: CREATED, UPDATED, SKIPPED, WARNING, ERROR

CREATED / UPDATED are mutually exclusive success paths

SKIPPED means the row was not processed (missing required field, duplicate within the same file, etc.)

WARNING means the EP was created/updated but some non-fatal issue was detected (ambiguous Person match, custom-list value not auto-created, race number conflict)

ERROR means an exception occurred processing the row; the row was not committed

Each response carries the row’s firstName, lastName, registrationId, and a human-readable message

Response contains: totalRows, created, updated, skipped, warnings, errors

Invariant: totalRows == created + updated + skipped + warnings + errors

Rows with outcome CREATED or UPDATED are not individually listed (summary counters are sufficient)

Rows with outcome SKIPPED, WARNING, or ERROR appear in issues with full row context

A clean import has issues = [] and created + updated == totalRows

Second import produces updated == first-run.created + first-run.updated, created == 0

EventParticipant.id values are preserved across runs

Associated Person, Address, RaceNumber assignments, and order line items are not duplicated

A row that throws an exception is recorded with outcome ERROR and a diagnostic message

Subsequent rows continue to be processed

The response HTTP status is 200 OK even when some rows errored (operator reads the summary to decide next action)

Logs contain stack traces for every errored row with enough context (row number, identity, registration id) to locate the source line in the file

PERSON_EXTERNAL_ID (aliases UID, PID) is stored on the Person record when supplied

EVENT_PARTICIPANT_EXTERNAL_ID (alias EPREF) is stored on the EventParticipant.externalId when supplied

The same external id appearing in a later import does not cause a re-link (external ids are write-once-on-create unless the upsert key matches)

External ids are scoped to the organisation; collisions across orgs are permitted

ID_TYPE default: NATIONAL

ID_COUNTRY default: ZA

ORDER_STATUS default: P (Pending)

All other non-required columns default to null

Defaults are applied consistently regardless of HTTP delivery mode