Stages, Rounds & Progression
Stages
A project is broken into stages — for example a group stage followed
by a knockout stage. A stage's stage_type is a free-text field (up to
100 characters) rather than a fixed list of options, so what values are
meaningful is a convention of the project rather than something the
system enforces. Stages carry a name, an optional alias, a
sequence_number used to order them, an optional parent_id linking a
stage to a parent stage, and optional start_date/end_date values. A
stage's code is generated automatically from its name if left blank
when creating it, and is kept unique within the project.
Rounds
A round belongs to a single stage (stage_id is required) and
represents a subdivision of that stage's schedule — matchdays, legs, or
similar, depending on the sport. Like stage_type, a round's
round_type is free text rather than an enum, defaulting to standard.
Rounds do have a fixed lifecycle_state: draft, active, completed,
or cancelled, defaulting to draft. A required sequence_number
(minimum 1) orders rounds within their stage.
Stage entries
By default a stage inherits all of the project's entries. A stage can
instead be switched to explicit entry assignment, controlled by its
entry_selection_mode — inherit_project or explicit. In
inherit_project mode no explicit assignment is stored, and any existing
manual assignment for the stage is cleared. In explicit mode, the
entries you pick are written as stage_entry records (marked as manually
assigned) and only those entries take part in the stage; every entry
picked must belong to the same project as the stage.
Stage transitions
A stage transition connects a source stage to a target stage,
carrying entries from one to the other — the mechanism behind, for
example, promoting the top finishers of a group stage into a knockout
bracket. A transition defines how its entries are selected via
selector_type:
all_entries— every entry linked to the source stage (respecting that stage's own entry-selection mode).standing_rank_range— entries ranked within arank_from–rank_towindow of the source stage's current standings, within a chosenstanding_scope.match_outcome— winners or losers (match_outcome) of the source stage's matches, optionally narrowed to onesource_round_id. If a match has no explicit winner/loser result but does have numeric scores for every participant, the higher (or lower, depending on the sport profile) score is used as the tie-break.manual— no entries are resolved automatically; assignment has to be done directly on the target stage's entries.
A transition also has a carry_over_mode (none, all_results, or
mutual_results) and an optional target_seed_start, which — when set —
assigns sequential seed numbers to the resolved entries as they land in
the target stage.
Stage progression
The stage progression screen is where a transition is previewed and, for
any selector other than manual, applied. Previewing resolves the
transition's current candidate entries and computes a checksum over the
transition's configuration plus those resolved entries, which is used to
detect whether an identical run has already been applied.
Applying a transition assigns the resolved entries into the target
stage — adding new stage_entry records as needed, removing entries that
are no longer resolved (as long as nothing else still depends on them),
and switching the target stage's entry_selection_mode to explicit in
the process. If the checksum from the preview matches a previous run
exactly, that run is reused rather than duplicated. Applying is only
possible for a user with the joomleague.project.run.transitions
permission on the project, and only when the transition's selector type
makes it executable — manual transitions never can be applied this way.