Skip to main content

Participant Governor

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.

const participant = {
  participantId, // automatically generated if not provided
  participantRole: COMPETITOR,
  participantType: INDIVIDUAL,
  person: {
    standardFamilyName: 'Family',
    standardGivenName: 'Given',
    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);

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,
});

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
  paricipantIds,
});

filterParticipants​

Filters participants based on provided criteria.

const { filteredParticipants } = engine.filterParticipants({
  tournamentRecord, // required
  participantFilters, // required - filter criteria object
  policyDefinitions, // optional
});

Purpose: Query participants with complex filtering criteria.

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.

getParticipantSignInStatus​

Returns sign-in status for a participant.

const { signInStatus } = engine.getParticipantSignInStatus({
  participantId, // required
  tournamentRecord, // required
});

Purpose: Check if participant has signed in for tournament/event.

getParticipantTimeItem​

Returns time items attached to a participant.

const { timeItem } = engine.getParticipantTimeItem({
  participantId, // required
  itemType, // required - time item type
  tournamentRecord, // required
});

Purpose: Query time-based metadata for participants.

getParticipants​

Returns participants with optional hydration and filtering.

const { participants, participantMap } = engine.getParticipants({
  tournamentRecord, // required
  participantFilters, // optional - filter criteria
  withMatchUps, // optional boolean
  withDraws, // optional boolean
  withEvents, // optional boolean
  withScaleValues, // optional boolean
  withSeeding, // optional boolean
  withSignInStatus, // optional boolean
  policyDefinitions, // optional
  internalUse, // optional boolean
});

Purpose: Primary method for retrieving participants with rich context.

getScaleValues​

Returns all scale values (rankings/ratings) for participants.

const { scaleValues } = engine.getScaleValues({
  tournamentRecord, // required
  scaleAttributes, // optional - filter to specific scale
});

Purpose: Get all ratings/rankings across all participants.

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,
});

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 of a participant.

engine.modifyParticipantOtherName({
  participantId, // required
  otherName, // required - new other name
  tournamentRecord, // required
});

Purpose: Update participant's alternate name field.

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 });

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 });

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.

publicFindParticipant​

Finds a participant using public-facing search criteria (typically for public APIs).

const { participant } = engine.publicFindParticipant({
  tournamentRecord, // required
  participantId, // optional
  personId, // optional
  policyDefinitions, // optional - privacy policies applied
});

Purpose: Query participants with privacy policies applied for public APIs.

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​

const { valid, error, errors } = engine.validateLineUp({
  tieFormat, // required to validate collectionIds in lineUp
  lineUp,
});