Skip to main content

Participant Governor

Governor API transition at 8.0.0

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.

note

To add PAIR participants it is only necessary to provide an array of 2 valid individualParticipantIds, participantType and participantRole.

note

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.

note
  • participantIds are unique within a tournament
  • personIds are 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 with createdAt.
  • Re-pointing is explicit: if the participant already carries a different personId from that organisation, the call refuses with EXISTING_PERSON_OTHER_ID (its context names the existing ids) unless replaceExisting: true is passed. With the flag, the kept entry's personId is replaced and updatedAt is 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 — when organisationId or personId is empty.
  • PARTICIPANT_NOT_FOUND — when no participant matches.
  • INVALID_VALUES — when the participant is not INDIVIDUAL (has no person object). Only INDIVIDUAL participants accept personOtherIds.
  • EXISTING_PERSON_OTHER_ID — when the organisation already has a different id on this person and replaceExisting is 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_ASSIGNMENT when 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_PARTICIPANTS when none of the participantIds is in the tournament;
  • a refusal from removing their entries, as removeEventEntries would 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
},
});
  • homeVenueIds is replaced, not merged, and duplicates collapse. Only a TEAM has home venues (INVALID_PARTICIPANT_TYPE otherwise); a venueId that is not a venue of the tournament is refused with VENUE_NOT_FOUND, naming it in venueIds. A TEAM's home venues are what resolveHomeParticipantId reads for its VENUE basis.
  • An unrecognised participantStatus, a representing that is not a country code, or a non-boolean useOtherName is refused with INVALID_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:

  • undefined and null leave 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 (or INVALID_PARTICIPANT_TYPE, INVALID_PARTICIPANT_IDS, PARTICIPANT_NOT_FOUND, INVALID_DATE where those fit), with context.field naming the attribute (for example person.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​

  • participantRole must be a participant role ('' clears it). participantName must be a non-empty string.
  • notes is stored as a string ('' clears it). addNotes cannot reach a stored participant through the engine.
  • contacts, onlineResources and participantRoleResponsibilities must be arrays, and they replace the stored lists.
  • onlineResources entries are CODES OnlineResource objects, checked as person.onlineResources is: the type is resourceType, one of SOCIAL_MEDIA, URL, EMAIL or OTHER, and an attribute CODES does not define (such as resource in place of resourceType) is refused. A stored list that holds such an entry can still be sent back unchanged; a changed list must be all CODES entries.
  • individualParticipantIds must 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 unless pairOverride: true is passed. An INDIVIDUAL has no members (INVALID_PARTICIPANT_TYPE).
  • person is refused on a participant that is not an INDIVIDUAL.
  • groupingParticipantId is 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​

AttributeWhat modifyParticipant does
timeItemsMerged. 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.personOtherIdsMerged, 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.
extensionsRefused when changed; use addParticipantExtension / removeParticipantExtension.
penaltiesRefused when changed; use addPenalty / modifyPenalty / removePenalty.
presenceRefused when changed; use modifyParticipantsSignInStatus.
participantOtherIdsRefused when changed; use addParticipantOtherId.
person.extensions, person.timeItemsRefused 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 });
note

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.

info

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.

note

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. With protectedIdPolicy: '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.