Skip to main content

Actions

Overview​

The engines of the Competition Factory preserve the integrity of tournament records, which means that errors are thrown when invalid actions are attempted, such as removing an outcome for a matchUp when participants have already progressed and completed subsequent matchUps in an elimination structure.

In developing a User Interface for interaction with draw structures it is useful to know in advance which actions are valid. The Competition Factory exports two methods which return not only validActions but also the methods to perform each action, along with both pre-populated parameters and valid values for parameters which are yet to be defined.

Action Validation​

Actions are validated based on:

  • Draw structure integrity: Can't remove participants if dependent matches have been played
  • Tournament state: Some actions only available before/after draw publication
  • Participant status: Can't withdraw already withdrawn participants
  • Policy constraints: Position Actions and MatchUp Actions policies can restrict available actions
Policy Configuration

Available actions can be customized using policies:

positionActions​

Actions which are relevant to assigned positions within a draw structure. These actions manage participant placement, seeding, and draw position assignments.

Supported Actions​

Participant Assignment:

  • Assign Participant - Assign accepted/selected participants to specified draw position
  • Assign Alternate - Assign participant from the list of alternates to specified draw position
  • Assign Qualifier - Assign qualifier from Qualifying structure to specified draw position
  • Assign Lucky Loser - Assign loser from Qualifying structure to specified draw position
  • Remove Assignment - Clear specified draw position
  • Withdraw Participant - Clear specified draw position and withdraw participant from event

Draw Position Management:

  • Assign Bye - Assign a BYE to specified draw position
  • Swap Participants - Swap participant at specified draw position with any other positioned participant
  • Modify Pair Assignment - Modify individual participant within a positioned doubles pair participant

Seeding:

  • Set Seed Value - Assign custom seed value to participant at draw position
  • Remove Seed Value - Remove seed assignment from participant at draw position

Display:

  • Set Nickname - Set a nickname for assigned participant (useful when players have excessively long names or multiple players have the same name)

Administrative:

  • Add Penalty - Record a penalty for participant at specified draw position

Usage​

const { validActions, isByePosition } = tournamentEngine.positionActions({
  drawId: 'draw-123',
  structureId: 'structure-456',
  drawPosition: 1
});

// validActions is an array of available action objects
validActions.forEach(action => {
  console.log(`${action.type}: ${action.method}`);
  // Each action includes:
  // - type: action name
  // - method: engine method to call
  // - payload: pre-populated parameters
  // - availableOptions: valid values for user selection
});

Policy Configuration​

Position actions can be restricted using the Position Actions Policy:

tournamentEngine.attachPolicies({
  policyDefinitions: {
    positionActions: {
      policyName: 'Restricted',
      // Disable specific actions
      disableAssignQualifier: true,
      disableAssignLuckyLoser: true,
      // Only allow actions before draw publication
      requireUnpublished: true
    }
  }
});

API Reference​

askEngine.positionActions()

See Also:

matchUpActions​

Actions which are relevant to a specific matchUp within a draw structure. These actions manage match outcomes, scheduling, officials, and team lineups.

Supported Actions​

Match Outcomes:

  • Set Score - Submit either complete or partial score for specified matchUp
  • Set Status - Submit matchUpStatus for specified matchUp (e.g., WALKOVER, DEFAULTED, RETIRED)

Scheduling:

  • Set Schedule - Submit scheduling details for specified matchUp (date, time, court, venue)
  • Set Start Time - Set start time for specified matchUp
  • Set End Time - Set end time for specified matchUp

Officials:

  • Assign Referee - Set Referee Participant for specified matchUp
  • Add Officials - Assign additional officials (line judges, supervisors)

Administrative:

  • Add Penalty - Record a penalty for participant within specified matchUp

Team Events (TEAM matchUpType):

  • Assign Lineup Position - Assign participant to lineup position for specified matchUp
  • Remove Lineup Position - Remove participant from lineup position for specified matchUp
  • Replace Lineup Position - Replace participant assigned to lineup position for specified matchUp
  • Substitute Position Participant - Nominate substitute participant for lineup position for specified matchUp

Usage​

const { validActions, isByeMatchUp } = tournamentEngine.matchUpActions({
  matchUpId: 'matchup-789',
  drawId: 'draw-123'
});

// validActions is an array of available action objects
validActions.forEach(action => {
  console.log(`${action.type}: ${action.method}`);
  // Each action includes:
  // - type: action name
  // - method: engine method to call
  // - payload: pre-populated parameters
  // - options: valid values for user selection
});

// Example: Set score action
const scoreAction = validActions.find(a => a.type === 'SCORE');
if (scoreAction) {
  // scoreAction.payload includes matchUpId, drawId
  // scoreAction.options includes valid matchUpStatus values
  tournamentEngine[scoreAction.method]({
    ...scoreAction.payload,
    score: { sets: [{ side1Score: 6, side2Score: 4 }] },
    winningSide: 1
  });
}

Policy Configuration​

MatchUp actions can be restricted using the MatchUp Actions Policy:

tournamentEngine.attachPolicies({
  policyDefinitions: {
    matchUpActions: {
      policyName: 'TournamentDirector',
      // Disable certain actions for published draws
      disableScoreEntry: false,
      requireRefereeAssignment: true,  // Require referee before scoring
      // Control substitution rules
      substitutionLimits: {
        maxPerTeam: 2,
        maxPerPosition: 1
      },
      // Restrict scheduling actions
      enableScheduleModification: true,
      requireScheduleApproval: false
    }
  }
});

Match Status Actions​

Different matchUpStatus values trigger different actions:

  • TO_BE_PLAYED → Can set schedule, assign officials, enter lineups
  • IN_PROGRESS → Can set start time, update score
  • COMPLETED → Can set end time, penalties; score modification restricted
  • WALKOVER/DEFAULTED → Can modify status, add penalties
  • SUSPENDED → Can add notes, set resume time

API Reference​

askEngine.matchUpActions()

See Also: