Participant Governor
Some methods on this page are candidates for removal from production engine exports at the 8.0.0 boundary. Their implementation references have moved: getParticipantTimeItem, getScaleValues, validateLineUp. Existing 7.x routes remain available; final decisions and external-integrator confirmations are tracked in the transition index.
import { participantGovernor } from 'tods-competition-factory';
addDynamicRatings
Attaches dynamic ratings generated by drawMatic to participants.
engine.addDynamicRatings({
modifiedScaleValues, // output of drawMatic; necessary in client/server scenarios
removePriorValues, // optional boolean
});
addParticipant
Adds an INDIVIDUAL, PAIR or TEAM participant to tournament participants. Includes integrity checks for { participantType: PAIR } to ensure participant.individualParticipantIds are valid. See examples: Participant Roles, Adding Individual Participants, Adding Teams.
To add PAIR participants it is only necessary to provide an array of 2 valid individualParticipantIds, participantType and participantRole.
For INDIVIDUAL participants, person.standardFamilyName and person.standardGivenName are required unless participantOtherName or participantName is provided. When person names are incomplete, participantName is automatically set from participantOtherName.
const participant = {
participantId, // automatically generated if not provided
participantRole: COMPETITOR,
participantType: INDIVIDUAL,
participantOtherName, // optional - nickname/display name; can substitute for person names
person: {
standardFamilyName: 'Family', // required unless participantOtherName/participantName provided
standardGivenName: 'Given', // required unless participantOtherName/participantName provided
nationalityCode, // optional
sex, // optional
},
};
engine.addParticipant({ participant });
addParticipants
Bulk add participants to a tournamentRecord. See examples: Tournament Entry with Ratings, setTournamentId, setTournamentId.
engine.addParticipants({ participants });
addPenalty
Add a penaltyItem to one or more participants.
const createdAt = new Date().toISOString();
const penaltyData = {
refereeParticipantId, // optional
participantIds: ['participantId'],
penaltyCode: 'Organization specific code', // optional
penaltyType: BALL_ABUSE,
matchUpId,
issuedAt, // optional ISO timeStamp for time issued to participant
createdAt,
notes: 'Hit ball into sea',
};
let result = engine.addPenalty(penaltyData);
penaltyType is a PenaltyTypeEnum code (BALL_ABUSE is 'BALL_ABUSE'), and the code is what is stored; render it through @courthive/i18n (penalties.<CODE>). A legacy value from earlier releases, a display label ('Ball Abuse') or a misspelling (EQUIMENT_VIOLATION, FAILUIRE_TO_SIGN_IN, 'Unsportmanlike Conduct', 'Puncuality'), is still accepted and stored as its code; 8.0.0 stops accepting them. See penaltyConstants.
addPersons
Creates tournament participants from an array of defined persons. Useful for adding registered persons to a tournament record.
See person under participant in Type Definitions for additional person attributes.
participantIdsare unique within a tournamentpersonIdsare unique to an individual, and should be identical across tournaments.
const persons = [
{
personId, // optional - providing a personId allows person to be tracked across tournaments
participantExtensions, // optional - any relevant extensions for created participant
participantTimeItems, // optional - any relevant timeItems (e.g. rankings/ratings) for created participant
standardFamilyName,
standardGivenName,
nationalityCode,
sex,
// optional - will create pair participants
pairedPersons: [
{
participantExtensions, // optional - any relevant extensions for created participant
participantTimeItems, // optional - any relevant timeItems (e.g. rankings/ratings) for created participant
personId,
},
],
},
];
engine.addPersons({
participantRole, // optional - defaults to COMPETITOR
persons,
});
addPersonOtherId
Adds a UnifiedPersonID entry to the participant's person.personOtherIds[] array, or re-points an existing one when asked to. Only valid on INDIVIDUAL participants (the ones that have a person object).
engine.addPersonOtherId({
participantId, // required
organisationId, // required — the federation / registry identifier (string)
personId, // required — the externalId issued by that organisation
replaceExisting, // optional — required to re-point an existing, different id
});
Semantics:
- Keyed by
organisationId: with no entry for the organisation, a new entry is appended withcreatedAt. - Re-pointing is explicit: if the participant already carries a different
personIdfrom that organisation, the call refuses withEXISTING_PERSON_OTHER_ID(itscontextnames the existing ids) unlessreplaceExisting: trueis passed. With the flag, the kept entry'spersonIdis replaced andupdatedAtis stamped, and any duplicate entries for that organisation are collapsed into it. An identity link is never re-pointed by accident; an application can route the refusal to a review step and re-apply with the flag once approved. - Idempotent: re-applying the same
(organisationId, personId)is a no-op. The array does not grow. - Federation-agnostic: the factory does not validate or interpret
organisationId. Callers choose what to use — a federation abbreviation ('USTA','ITA','HTS','CTS'), a canonical-registry name, anything stable and meaningful within the consuming application.
Errors:
MISSING_TOURNAMENT_RECORD,MISSING_PARTICIPANT_ID— standard parameter checks.MISSING_VALUE— whenorganisationIdorpersonIdis empty.PARTICIPANT_NOT_FOUND— when no participant matches.INVALID_VALUES— when the participant is not INDIVIDUAL (has nopersonobject). Only INDIVIDUAL participants acceptpersonOtherIds.EXISTING_PERSON_OTHER_ID— when the organisation already has a different id on this person andreplaceExistingis not set.
Purpose: Establish a stable, queryable link between a TODS participant and an external identity — a federation member roster, a canonical person registry, or any other identifier-issuing system. The mutation is the write-half of the TODS personOtherIds shape; reads use that array directly.
addPersonRequests
Validates and adds person requests.
const requests = [
{
date, // 'YYYY-MM-DD' date string
startTime, // '00:00' time string
endTime, // '00:00' time string
requestType: 'DO_NOT_SCHEDULE',
},
];
engine.addPersonRequests({ personId, requests });
addIndividualParticipantIds
Adds individualParticipantIds to GROUP or TEAM participants
engine.addIndividualParticipantIds({
individualParticipantIds,
groupingParticipantId,
removeFromOtherTeams, // optional boolean
});
createTeamsFromParticipantAttributes
Uses attributes of individual participnts or persons to generate { participantType: TEAM } participants.
Returns count of # of TEAM participants added;
const { participantsAdded } = engine.createTeamsFromParticipantAttributes({
participantAttribute, // optional -- attribute of participant object
addParticipants, // optional boolean; defaults to true; when false return new participants
personAttribute, // optional - attribute of person object
accessor, // optional - use accessor string to retrieve nested value (even from person address arrays)
uuids, // optional - uuids to assign to generated participants
});
createGroupParticipant
Creates a GROUP participant from individual participants.
const { participant, participantId } = engine.createGroupParticipant({
individualParticipantIds, // required - array of participant IDs
groupName, // required - name for the group
participantRole, // optional - defaults to OTHER
participantRoleResponsibilities, // optional - array of strings
participantId, // optional - provide specific ID
});
Purpose: Create group participants for officials, support staff, or other grouped entities.
deleteParticipants
engine.deleteParticipants({
addIndividualParticipantsToEvents, // optional boolean
participantIds,
});
Deleting an INDIVIDUAL also deletes every PAIR that contains them. Every refusal is decided before the first write, so a refused call changes nothing:
EXISTING_PARTICIPANT_DRAW_POSITION_ASSIGNMENTwhen a participant being deleted, or a PAIR deleted with one, is placed in a draw (a PAIR placed in a DOUBLES draw blocks the deletion of either of its individuals);CANNOT_REMOVE_PARTICIPANTSwhen none of theparticipantIdsis in the tournament;- a refusal from removing their entries, as
removeEventEntrieswould make it.
Entries are removed from every event, flight and draw for the participants deleted and for the PAIRs deleted with them, so no entry is left pointing at a deleted participant.
Notices: DELETE_PARTICIPANTS lists every participant actually removed (a PAIR removed along with its individual
participant is included), and groupings that lost a member are announced with MODIFY_PARTICIPANTS.
filterParticipants
Filters the participants passed in; it does not read the tournament's participants.
const filteredParticipants = engine.filterParticipants({
participants, // required - the participants to filter; none passed returns []
participantFilters, // filter criteria object; empty returns participants unfiltered
});
// returns an array (not an object)
Purpose: Query participants with complex filtering criteria.
findParticipant
Finds a participant by participantId or personId. A participant policy in policyDefinitions is applied to the
returned participant (the engine method is the function exported as publicFindParticipant).
const { participant } = engine.findParticipant({
participantId, // optional
personId, // optional
policyDefinitions, // optional - e.g. fixtures.policies.POLICY_PRIVACY_DEFAULT
});
getCompetitionParticipants
Returns all participants across multiple tournaments in a competition.
const { participants } = engine.getCompetitionParticipants({
tournamentRecords, // required - array of tournament records
});
Purpose: Aggregate participants from all tournaments in a competition.
getPairedParticipant
Returns the paired participant (doubles partner) for an individual participant.
const { participant } = engine.getPairedParticipant({
participantId, // required - individual participant ID
tournamentRecord, // required
});
Purpose: Find doubles partner in PAIR participants.
getParticipantEventDetails
Returns event-specific details for a participant including entries and matchUps.
const { eventDetails } = engine.getParticipantEventDetails({
participantId, // required
tournamentRecord, // required
});
Purpose: Get all event participation details for a participant.
getParticipantMembership
Returns team/group membership information for a participant.
const { membership } = engine.getParticipantMembership({
participantId, // required
tournamentRecord, // required
});
Purpose: Query which teams or groups a participant belongs to.
getParticipantScaleItem
Returns a specific scale item (rating/ranking) for a participant.
const { scaleItem } = engine.getParticipantScaleItem({
participantId, // required
scaleAttributes, // required - scale type to retrieve
tournamentRecord, // required
});
Purpose: Get specific rating or ranking value for a participant.
getParticipantSchedules
Returns all scheduled matchUps for a participant.
const { schedules } = engine.getParticipantSchedules({
participantId, // required
tournamentRecord, // required
});
Purpose: Get participant's schedule across all events.
getParticipantPaymentStatus
Returns the current payment status for a participant — one of PAID, UNPAID, PARTIAL, WAIVED, REFUNDED, or undefined if no payment status has ever been set. See modifyParticipantsPaymentStatus for the write side and history semantics.
const paymentStatus = engine.getParticipantPaymentStatus({
participantId, // required
tournamentRecord, // required
});
Purpose: Check whether the participant's registration fee has been paid, separately from whether they've physically signed in.
getParticipantSignInStatus
Returns sign-in status for a participant: the latest recorded presence state.
const signInStatus = engine.getParticipantSignInStatus({
participantId, // required
});
// 'SIGNED_IN' when the latest record is a sign-in; false when it is a sign-out;
// nothing (undefined) when no presence was ever recorded
Purpose: Check if participant has signed in for tournament/event.
getParticipantTimeItem
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to getParticipantTimeItem. Package-export status is a separate decision.
getParticipants
Returns participants with optional hydration and filtering. This is the primary method for retrieving participants with rich context including matchUps, events, draws, rankings, and schedule information.
const {
participants, // HydratedParticipant[]
participantMap, // { [participantId]: participantData }
matchUps, // HydratedMatchUp[] (when withMatchUps)
mappedMatchUps, // matchUps indexed by matchUpId
participantIdsWithConflicts, // participantIds with schedule conflicts
eventsPublishStatuses, // publish statuses keyed by eventId
derivedEventInfo, // derived event metadata
derivedDrawInfo, // derived draw metadata
missingParticipantIds, // participantIds referenced but not found
} = engine.getParticipants({
participantFilters, // optional — filter criteria object
policyDefinitions, // optional — privacy/display policies
scheduleAnalysis, // optional — schedule conflict detection parameters
contextProfile, // optional — control context attributes on matchUps
contextFilters, // optional — filters based on context attributes
matchUpFilters, // optional — filters for matchUps
withIndividualParticipants, // optional boolean or object template — hydrate individualParticipants
withPotentialMatchUps, // optional boolean — include potential upcoming matchUps
withRankingProfile, // optional boolean — include ranking profile (implies withMatchUps/Events/Draws)
withScheduleItems, // optional boolean — include schedule items
withSignInStatus, // optional boolean — include sign-in status
withTeamMatchUps, // optional boolean — include TEAM matchUps
withScaleValues, // optional boolean — include ratings/rankings
usePublishState, // optional boolean — filter by publish state
withStatistics, // optional boolean — include statistical data
withOpponents, // optional boolean — include opponent data
withMatchUps, // optional boolean — include matchUp data
convertExtensions, // optional boolean — convert extensions to flat properties
withSeeding, // optional boolean — include seeding data
withEvents, // optional boolean — include event entries
withDraws, // optional boolean — include draw entries
withISO2, // optional boolean — include ISO2 country codes
withIOC, // optional boolean — include IOC country codes
returnParticipantMap, // optional boolean — defaults to true; false also lets filtered calls build less (below)
returnMatchUps, // optional boolean — defaults to true
internalUse, // optional boolean
});
Purpose: Primary method for retrieving participants with rich context.
A participant with no participantRole is a COMPETITOR. CODES requires only participantId, so hand-built
and older records can carry players with no role. participantFilters.participantRoles: [COMPETITOR] keeps them, and
[OFFICIAL] (or any other role) does not. The same read-time default applies wherever the factory decides by role
(event entry, team generation, entry status reports, tournament info counts, public participant rows); the record is
never rewritten. getTournamentInconsistencies lists such participants as PARTICIPANT_ROLE_MISSING (info). Only a
missing role is defaulted: a value that is not a participant role (e.g. "PLAYER") matches no role filter and is
reported as PARTICIPANT_ROLE_INVALID (warning).
Filtered lookups are cheapest with returnParticipantMap: false. The participantMap holds every participant
whether or not the filters keep it, so returning it means building the whole pool. When it is not returned, the
participantFilters are applied to the stored participants first, and only those kept are built, together with their
individuals and the groups they belong to (so groupings read the same). The result is the same as building
everything; on a 3,600-participant tournament, a lookup of the officials goes from ~118 ms to ~1 ms.
The whole pool is still built when a filter uses accessorValues (which may read attributes only a built participant
holds), or when any of withMatchUps, withDraws, withOpponents, withStatistics, withScheduleItems,
withPotentialMatchUps, withTeamMatchUps, withRankingProfile or scheduleAnalysis is requested, since those read
other participants.
const { participants: officials } = engine.getParticipants({
participantFilters: { participantRoles: [OFFICIAL] },
returnParticipantMap: false,
});
getParticipation
Derive what a tournamentRecord asserts about who took part — the rows a participation index is built from, without loading anything but this record.
const entries = engine.getParticipation({ tournamentRecord });
interface ParticipationEntry {
subjectType: 'TEAM' | 'PERSON'; // the grain the subject is identified at
subjectId: string; // the id an organisation ISSUED — stable across tournamentRecords
organisationId?: string; // the body that issued it; two may both number the same competitor
participantId: string; // this record's own id — tournament-local, never a subject key
tournamentId: string;
tournamentName?: string;
startDate?: string;
endDate?: string;
eventCount: number;
providerId?: string;
}
The counterpart to getTournamentCalendarEntry. A calendar entry answers what does this provider own; participation answers what did this competitor take part in. They are different relations and a calendar cannot express the second: a record lives in exactly one provider's calendar, while a team fixture belongs to the seasons of both sides, so ownership can only ever name one of them.
That is also why participation reads both sides of every fixture and needs no notion of a host — useful, because a source stating who hosted is the exception rather than the rule.
Subject identity comes from the issued id, never from participantId
A participantId is tournament-local: the same competitor carries a different one in every record it appears in. Keyed on that, a competitor's history would be exactly one entry long per record — plausible-looking, and wrong in a way nothing errors on.
The subject is therefore read from participantOtherIds (TEAM) and person.personOtherIds (PERSON), which carry the issuing organisation's own id and are stable by construction.
A competitor stating no issued id contributes no entry. That is a recorded gap — this record does not say who the competitor is in any durable sense — and manufacturing one from the local id would produce precisely the wrong answer above. Callers wanting to detect the gap can compare the entry count against the competitors they expected.
A competitor issued ids by two organisations yields one entry per organisation, which is correct: each is a distinct claim about identity, and a consumer indexes whichever body it speaks for.
Pure: reads only the record. Storage keys, timestamps and server-specific projections are the caller's concern.
getScaleValues
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to getScaleValues. Package-export status is a separate decision.
mergeParticipants
Merge participants array with existing tournament participants. Useful when synchronizing with a remote registration service, for example.
engine.mergeParticipants({ participants });
modifyIndividualParticipantIds
Modify individualParticipantIds of a grouping participant { participantType: TEAM || GROUP }.
engine.devContext(true).modifyIndividualParticipantIds({
groupingParticipantId, // participant (TEAM or GROUP) to which participantIds are to be added
individualParticipantIds: newIndividualParticipantIds,
});
modifyParticipant
Modifies attributes of a participant with integrity checks to ensure valid values for e.g. { participantType, participantRole }. Adds participant if not found.
engine.modifyParticipant({
participant: updatedIndividualParticipant,
});
Writing contacts
person.contacts (and participant.contacts) is replaced, not merged — deliberately, so that removing a contact is expressible. Read the existing array, change it, and send the whole thing back; sending only the contact you edited deletes the rest. Omitting the key leaves the stored list untouched, and [] clears it. See Contact Information.
PARTICIPANT_NAME_DERIVED_FROM_PERSON
A supplied participantName can be superseded by a derived one — from person for an INDIVIDUAL, or from the individuals of a PAIR. That precedence is intended, but returning plain success while silently dropping a value the caller passed makes a partial no-op indistinguishable from a full success. So when it happens the response carries an info:
const result = engine.modifyParticipant({
participant: {
participantId,
participantName: 'Ignored',
person: { standardGivenName: 'Roger', standardFamilyName: 'Federer' },
},
});
// result.success → true
// result.info → PARTICIPANT_NAME_DERIVED_FROM_PERSON
// the stored participantName is 'Roger Federer'
The key is conditional: callers that did not hit the precedence see the response shape they always have, so nothing needs to start checking for it.
Home venues, status, representing, useOtherName
These used to return success while the value was dropped. They are written now, and an invalid value is refused before anything is written:
engine.modifyParticipant({
participant: {
participantId, // a TEAM
homeVenueIds: [venueId], // venues of this tournament; [] clears
participantStatus: 'WITHDRAWN', // ACTIVE | WITHDRAWN; '' clears
representing: 'FRA', // an ISO or IOC country code; '' clears
useOtherName: true, // boolean
},
});
homeVenueIdsis replaced, not merged, and duplicates collapse. Only a TEAM has home venues (INVALID_PARTICIPANT_TYPEotherwise); a venueId that is not a venue of the tournament is refused withVENUE_NOT_FOUND, naming it invenueIds. A TEAM's home venues are whatresolveHomeParticipantIdreads for itsVENUEbasis.- An unrecognised
participantStatus, arepresentingthat is not a country code, or a non-booleanuseOtherNameis refused withINVALID_VALUES. - Omitting a key leaves it untouched. A value equal to the one already stored is never refused: consumers send the whole participant on every save, so a home venue since deleted does not block an unrelated edit.
Write or refuse: no attribute is dropped
Every attribute modifyParticipant is given is either written or the call is refused. None is accepted
and silently dropped. The rules below keep "send the whole participant back on every save" working:
undefinedandnullleave an attribute untouched.''clears an optional scalar, and an empty array or object clears a list or object attribute.- A value equal to the stored one is never refused, whatever it is. A legacy role, a one-letter name or a home venue that has since been deleted does not block an unrelated edit.
- Every check runs before the first write, so a refused call changes nothing, including the valid attributes sent in the same call.
- Refusals are
INVALID_VALUES(orINVALID_PARTICIPANT_TYPE,INVALID_PARTICIPANT_IDS,PARTICIPANT_NOT_FOUND,INVALID_DATEwhere those fit), withcontext.fieldnaming the attribute (for exampleperson.addresses[0].countryCode).
Person attributes
All of the CODES Person attributes are written, each checked against the CODES schema:
engine.modifyParticipant({
participant: {
participantId,
person: {
standardFamilyName: 'Yamada', // at least two characters; '' clears and re-derives participantName
standardGivenName: 'Taro',
nationalityCode: 'JPN', // see the warning below
nativeFamilyName: '山田', // string
nativeGivenName: '太郎', // string
passportFamilyName: 'YAMADA', // string
passportGivenName: 'TARO', // string
otherNames: ['Taro Y'], // array of strings
previousNames: ['Taro Suzuki'], // array of strings
birthYear: 1999, // whole year from 1900 to the current year
wheelchair: false, // boolean
tennisId: 'T-1', // string; '' clears
parentOrganisationId: 'org', // string
sectionId: 'section', // string
status: 'ACTIVE', // string
notes: 'note', // string
addresses: [{ addressType: 'HOME', city: 'Osaka', countryCode: 'JPN' }], // CODES Address objects
onlineResources: [{ resourceType: 'URL', identifier: 'https://example.org' }], // CODES OnlineResource objects
biographicalInformation: { playingHand: 'RIGHT', height: 180, heightUnit: 'CENTIMETER' },
},
},
});
addresses, onlineResources and biographicalInformation (with its teamAttributes) are closed objects: an
attribute CODES does not define, a wrong type or a value outside an enumeration is refused. Lists are replaced, not
merged.
nationalityCode is the one exception to refusal. A string that is not a recognised country code is written,
and the result carries a warning in the factory's warnings shape:
const result = engine.modifyParticipant({ participant: { participantId, person: { nationalityCode: 'XKX' } } });
// result.success → true
// result.warnings → [{ code: 'NATIONALITY_CODE_UNRECOGNIZED', message, participantId, nationalityCode: 'XKX' }]
A nationalityCode that is not a string is refused.
Participant attributes
participantRolemust be a participant role (''clears it).participantNamemust be a non-empty string.notesis stored as a string (''clears it).addNotescannot reach a stored participant through the engine.contacts,onlineResourcesandparticipantRoleResponsibilitiesmust be arrays, and they replace the stored lists.onlineResourcesentries are CODES OnlineResource objects, checked asperson.onlineResourcesis: the type isresourceType, one ofSOCIAL_MEDIA,URL,EMAILorOTHER, and an attribute CODES does not define (such asresourcein place ofresourceType) is refused. A stored list that holds such an entry can still be sent back unchanged; a changed list must be all CODES entries.individualParticipantIdsmust be INDIVIDUAL participants of the tournament. An id the grouping already holds but that no longer exists is tolerated and removed. A PAIR must have exactly two members unlesspairOverride: trueis passed. An INDIVIDUAL has no members (INVALID_PARTICIPANT_TYPE).personis refused on a participant that is not an INDIVIDUAL.groupingParticipantIdis checked before anything is written. It must be a TEAM or GROUP of the tournament, and only an INDIVIDUAL can join it.
Attributes with their own setters
| Attribute | What modifyParticipant does |
|---|---|
timeItems | Merged. A new rating or ranking (SCALE.RATING.*, SCALE.RANKING.*) is added the way setParticipantScaleItem adds one: appended when its value differs from the current one. Nothing stored is ever deleted. Any other new timeItem is refused, naming addParticipantTimeItem. |
person.personOtherIds | Merged, as addPersonOtherId does: upserted by organisationId, or by uniqueOrganisationName when an entry has no organisationId. A new name-only entry stores the name as its organisationId, which CODES requires. Entries the caller omits are kept. |
extensions | Refused when changed; use addParticipantExtension / removeParticipantExtension. |
penalties | Refused when changed; use addPenalty / modifyPenalty / removePenalty. |
presence | Refused when changed; use modifyParticipantsSignInStatus. |
participantOtherIds | Refused when changed; use addParticipantOtherId. |
person.extensions, person.timeItems | Refused when changed; there is no write path. |
Ignored on purpose
Metadata is ignored and never refused: isMock, createdAt, updatedAt, personId and teamId on the
participant, and isMock, createdAt and updatedAt on the person. Attributes that are not part of a CODES
participant are ignored too, such as those getParticipants adds when hydrating.
modifyParticipantName
Updates the name of a participant.
engine.modifyParticipantName({
participantId, // required
participantName, // required - new name
tournamentRecord, // required
});
Purpose: Change participant's display name.
modifyParticipantOtherName
Updates the alternate/other name (nickname) of a participant. Also available as a position action (ADD_NICKNAME) in draw views.
engine.modifyParticipantOtherName({
participantId, // required
participantOtherName, // new nickname; pass undefined to clear
});
Purpose: Set or clear a participant's display nickname. When participantOtherName is set, it is used as the display name in draw structures (via renderParticipant) in preference to participantName. For participants without structured person names (standardFamilyName/standardGivenName), the participantOtherName also serves as the required identity — see Participants Without Structured Names.
modifyPersonRequests
Modifies existing person requests.
Any requests without a requestId will be added. Any requests without requestType will be removed.
engine.modifyPersonRequests({
personId, // optional - scope to single personId; avoid brute-force updates
requests: [
{
requestType,
requestId, // if requestId is not present, will attempt to added
startTime,
endTime,
date,
},
],
});
modifyPenalty
const penaltyData = {
participantIds: ['participantId'],
notes: 'Hit ball into sea',
penaltyType: BALL_ABUSE,
matchUpId,
issuedAt,
};
let result = engine.addPenalty(penaltyData);
const { penaltyId } = result;
const notes = 'Hit ball into spectator';
const modifications = { notes };
engine.modifyPenalty({ penaltyId, modifications });
A penaltyType modification with a legacy label or misspelling (see addPenalty) is rewritten to its code before it is stored, until 8.0.0.
modifyParticipantsPaymentStatus
Modify the payment status of multiple participants, referenced by participantId. Stored as a participant timeItem with itemType: 'PAYMENT_STATUS', so successive calls preserve history via previousItems on getTimeItem. Use this to record registration-fee payment independently of sign-in (which only tells you whether a player physically checked in on tournament day).
Valid paymentState values: PAID, UNPAID, PARTIAL, WAIVED, REFUNDED. PARTIAL is intended for doubles or installment scenarios where one component has paid and the other has not; WAIVED for comps, sponsorships, or fee waivers; REFUNDED for participants who paid but were later refunded.
import { factoryConstants } from 'tods-competition-factory';
const { PAID, REFUNDED } = factoryConstants.participantConstants;
engine.modifyParticipantsPaymentStatus({
participantIds: ['participantId'],
paymentState: PAID,
});
// Later — issue a refund. PAID stays in previousItems; current becomes REFUNDED.
engine.modifyParticipantsPaymentStatus({
participantIds: ['participantId'],
paymentState: REFUNDED,
});
Read the current value with getParticipantPaymentStatus:
const paymentStatus = engine.getParticipantPaymentStatus({ participantId });
// → 'PAID' | 'UNPAID' | 'PARTIAL' | 'WAIVED' | 'REFUNDED' | undefined
modifyParticipantsSignInStatus
Modify the signInStatus of multiple participants, referenced by participantId.
engine.modifyParticipantsSignInStatus({
participantIds: ['participantId'],
signInState: SIGNED_IN,
});
regenerateParticipantNames
Regenerate .participantName for SINGLES and DOUBLES participants.
Upper/lower case and order are derived from personFormat string which must contain "last" and may contain "first" or "f", for first initial.
const formats = {
PAIR: { personFormat: 'LAST', doublesJointer: '/' },
INDIVIDUAL: { personFormat: 'LAST, First' },
};
engine.regenerateParticipantNames({ formats });
Participants without standardGivenName/standardFamilyName are skipped — their existing participantName is preserved. For PAIR participants, individual components without person names fall back to participantOtherName or participantName.
participantScaleItem
Utility function to extract a scale item (rating/ranking) from a participant object.
const { scaleItem } = participantScaleItem({
participant, // required - participant object
scaleAttributes, // required - scale type to retrieve
});
console.log(scaleItem.scaleValue);
Purpose: Low-level utility for extracting scale values from participant objects.
Note: Use getParticipantScaleItem for engine-level queries with participantId.
removePenalty
Removes a penalty from all relevant tournament participants.
engine.removePenalty({ penaltyId });
removePersonRequests
Removes person requests matching passed values. If no paramaters are provided, removes all person requests.
result = engine.removePersonRequests({
personId, // optional - scope to personId
requestType, // optioanl - scope to requestType
requestId, // optional - scope to a single requestId
date, // optional - scope to a specific date
});
removeRatings
Remove specified ratings from participants.
engine.removeRatings({
ratingType, // e.g. WTN, UTR
asDynamic, // optional boolean; remove DYNAMIC version of specified scaleName
eventType, // SINGLES or DOUBLES
});
scaledTeamAssignment
Assigns individual participants to teams using a waterfall pattern; removes UNGROUPED entries as appropriate for TEAM events. May be called with either individualParticipantIds and scaleAttributes or with an array of scaledParticipants.
By default existing individualParticipant assignments are cleared. If existing assignments are retained, any individualParticipant already assigned will be excluded from further assignment. It may be desirable to retain existing assignments if sequential assignment of different groups of individualParticipants is desired.
Modifying team assignments has "global" effect, meaning that if a team appears in multiple events, team membership will be changed for all events.
Example use with individualParticipantIds and scaleAttributes
const scaleAttributes = {
sortOrder: ASCENDING, // defaults to ASCENDING; use case for DESCENDING is unclear!
scaleType: RANKING,
eventType: SINGLES,
scaleName: 'U18',
};
engine.scaledTeamAssignment({
clearExistingAssignments, // optional - true by default remove all existing individualParticipantIds from targeted teams
individualParticipantIds, // individuals to be sorted by scaleAttributes and assigned to teams (WATERFALL)
reverseAssignmentOrder, // optional - reverses team order; useful for sequential assignment of participant groupings to ensure balanced distribution
teamParticipantIds, // optional, IF teamsCount is provided then teams will be created
initialTeamIndex, // optional - allows assignment to begin at a specified array index; useful for sequential assignment of groups of scaledParticipants
scaleAttributes, // ignored if scaledParticipants are provided; { scaleName, scaleType, sortOrder, eventType }
teamNameBase, // optional - defaults to '[categoryName] TEAM #', where categoryName is derived from eventId (if supplied)
teamsCount, // optional - derived from teamParticipantIds (if provided) - create # of teams if teamParticipantIds provided are insufficient
eventId, // optional - source team participants from DIRECT_ACCEPTANCE entries for specified event
});
Example use with scaledParticipants
const scaleAttributes = {
scaleType: RANKING,
eventType: SINGLES,
scaleName: 'U18',
};
const scaledParticipants = individualParticipants.map((participant) => ({
scaleValue: participantScaleItem({ participant, scaleAttributes }).scaleItem.scaleValue,
participantId: 'participantId',
}));
const teamParticipantIds = teamParticipants.map(getParticipantId);
engine.scaledTeamAssignment({
scaledParticipants, // [{ participantId: 'participantId', scaleValue: '10' }]
teamParticipantIds,
});
Example use with sequential assignment where there are 8 teams
In this scenario scaled MALE participants are assigned in a waterfall pattern beginning with the first team (default behavior); scaled FEMALE participants are then assigned in a reverse waterfall pattern beginning with the last team. The goal is to balance the teams to the greatest extent possible. This pattern can be used with an arbitrary number of groups of individualParticipants.
engine.scaledTeamAssignment({
scaledParticipants: maleScaleParticipants,
teamParticipantIds,
});
engine.scaledTeamAssignment({
scaledParticipants: femaleScaleParticipants,
clearExistingAssignments: false,
reverseAssignmentOrder: true,
initialTeamIndex: 7,
teamParticipantIds,
});
setParticipantScaleItem
scaleItem = {
scaleValue: 12,
scaleName: 'U16',
scaleType: RANKING,
eventType: SINGLES,
scaleDate: '2020-06-06',
};. See examples in [External Ranking Integration](../concepts/timeItems.md#external-ranking-integration), [RANKING](../concepts/scaleItems.md#ranking), [Complex Scale Item Retrieval](../concepts/accessors.mdx#complex-scale-item-retrieval).
result = engine.setParticipantScaleItem({
removePriorValues, // optional boolean - when true will delete prior timeItems
participantId,
scaleItem,
});
setParticipantScaleItems
const scaleItemsWithParticipantIds = [
{
participantId: 'participantId',
scaleItems: [
{
scaleValue: 8.3,
scaleName: 'WTN',
scaleType: RATING,
eventType: SINGLES,
scaleDate: '2021-01-01',
},
],
},
];
engine.setParticipantScaleItems({
removePriorValues, // optional boolean - when true will delete prior timeItems
scaleItemsWithParticipantIds,
// optional context, primarily used when adding SEEDING, useful for structureReports
context: {
scaleAttributes, // e.g. { scaleType: 'SEEDING' }
scaleBasis, // e.g. { scaleType: 'RANKING', scaleDate }
eventId,
},
});. See examples in [Multiple Scale Items](../concepts/scaleItems.md#multiple-scale-items).
validateLineUp
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to validateLineUp. Package-export status is a separate decision.
removeIndividualParticipantIds
Removes individualParticipantIds from a grouping participant (TEAM or GROUP). Handles integrity checks including lineUp cleanup for draws where the team is entered, and optionally adds removed individuals as UNGROUPED entries to events.
engine.removeIndividualParticipantIds({
groupingParticipantId, // required — participantId of the TEAM or GROUP
individualParticipantIds, // required — array of participantIds to remove
addIndividualParticipantsToEvents, // optional boolean — add removed participants as UNGROUPED event entries
suppressErrors, // optional boolean — continue on errors (e.g. participant not found in group)
});
See also: modifyIndividualParticipantIds, addIndividualParticipantIds.
addParticipantTimeItem
Adds a timeItem to a specific participant. TimeItems store time-based metadata such as rankings, ratings, and sign-in status.
engine.addParticipantTimeItem({
participantId, // required
timeItem, // required — { itemType, itemValue, ... } time item object
removePriorValues, // optional boolean — remove prior timeItems of the same itemType
duplicateValues, // optional boolean — allow duplicate values
});
getIndividualParticipantMergePreview
Preview consolidation of two existing INDIVIDUAL participants in one tournament. This query is read-only and returns
canMerge, fingerprint, the proposed participant, conflicts, blockers, changedPaths and affectedDrawIds.
A conflict path uses JSON Pointer notation (for example /person/birthDate); resolutions maps each conflicting
path to source or target. A preview can be successful while canMerge is false.
When both individuals are entered in the same event stage (or the same flight), the two entries collapse into the
survivor's entry, keeping its entryPosition. Any other registration field on which they differ (for example
entryStatus) is a conflict at the survivor entry's path, such as /events/0/entries/1/entryStatus, resolved like a
profile field.
The fingerprint covers what the operator reviews: both profiles, the proposed participant, choices, conflicts,
blockers, affected draws and every reference to be rewritten. Activity elsewhere in the tournament, such as scoring
on another court, does not invalidate a review.
The source is the duplicate to retire; the target is the participant ID to keep. Both individuals occurring in the same drawDefinition always blocks consolidation, including entries, nested structures, pairs, team rosters and lineups. Pair collapse, duplicate pairs, opposing-side overlap, duplicate lineups, conflicting entries/flights, trusted identity conflicts and unsupported ID-bearing extensions also block it. Different roles cannot be merged. Non-conflicting rating histories are retained. Divergent current ratings, presence or penalty histories require separate reconciliation in this version; they are never silently overwritten.
Issued ids (personOtherIds, participantOtherIds) are combined per issuing organisation. Copies of the same id that
differ only in their stamps collapse into one entry, keeping the earliest createdAt; two different ids from the same
organisation block as ISSUED_ID_CONFLICT.
Some organisations issue ids that identify a person beyond this tournament, such as a canonical person registry. The
caller names them in protectedIssuers (the factory does not decide which organisations matter). When exactly one
side carries a protected id, the preview adds warnings:
PROTECTED_ID_WOULD_MOVE— only the source carries it, so the id would move onto the survivor. Swapping source and target keeps it where it is. WithprotectedIdPolicy: 'refuse'this also becomes a blocker; the default,'warn', only reports it.PROTECTED_ID_ABSORBS_SOURCE— only the target carries it, so the person it identifies gains the duplicate's entries and results. This is reported, never refused.
Each warning names the organisationId and personId. warnings is present only when non-empty, so the
fingerprint of a review without warnings is unchanged.
mergeIndividualParticipants
Consolidate the two existing identities after preview. Unlike mergeParticipants, this removes one participant,
transfers supported references, retains the target ID and records the retired-ID mapping. Supply the reviewed
expectedFingerprint; missing/stale fingerprints return INDIVIDUAL_MERGE_STALE. Structural blockers and unresolved
field conflicts return INDIVIDUAL_MERGE_BLOCKED with the latest preview in context. Every refusal is atomic even
outside an execution queue. There is no force flag.
The result includes sourceParticipantId, targetParticipantId, changedPaths and a mergeReceipt holding the
reviewed choices and affected before-state. The server's durable command receipt stores this recovery data; it is
not a public notice or a global Persons merge. Consumers must keep receipts private. General unmerge is not provided.
resolveMergedParticipantId
Resolve a tournament-local retired participant ID to its retained ID. IDs without a mapping resolve to themselves.
Successive merges flatten the alias chain. A retired ID stays retired if
the retained participant is later deleted: it still resolves to the retained ID, so re-importing the person
re-creates the survivor rather than the duplicate. The individualParticipantMerges tournament extension survives record
export/import. Importers must resolve these IDs before deciding add/update/skip and before assigning event entries.
addParticipant, addParticipants and the existing mergeParticipants upsert refuse a retired ID with
PARTICIPANT_ID_RETIRED and context.canonicalParticipantId, so another importer cannot recreate the duplicate.