Synchronized, efficient, always growing.

Sport Structure Upload via Template (CSV)

Goal

Enable bulk upload of categories, leagues, and teams in the club active season from a CSV template.

This guide documents the actual implemented behavior in the sport structure screen.

Where it is used

Screen: SportStructureScreen
Button: Import CSV template
Requirement: user with club management permissions and screen in edit mode.

Reference files

Base template: sport_structure_import_template_en.csv

Required CSV format

Required headers (recommended order):

csv entity,name,category,league

Columns

entity: row type. Allowed values:

- category - league - team

name: main entity name.
category: required only when entity=team.
league: required only when entity=team.

Validation rules

Import validates before insert:

1. File must contain at least header + 1 data row. 2. Columns entity and name must exist. 3. If entity=team, category and league are required. 4. entity outside category|league|team is an error. 5. For teams, category/league must exist: - in active season DB, or - in the same file (if created as category/league rows).

If validation errors exist, import is not executed and an error summary is shown.

Insert behavior

New categories: inserted if they do not exist in active season (normalized name comparison).
New leagues: same criteria.
New teams: inserted if equivalent name+category+league combination does not exist.
Existing records are not deleted.
Existing names are not updated (append/partial upsert mode focused on new records).

Text normalization

Before compare/insert:

trim is applied;
multiple spaces collapse into one.

Example:

" Senior A " -> "Senior A"

Valid example

csv entity,name,category,league category,Senior,, category,Youth,, league,Gold,, league,Silver,, team,Senior Team A,Senior,Gold team,Senior Team B,Senior,Silver team,Youth Team A,Youth,Silver

Expected result:

Categories created: 2 (if they did not exist)
Leagues created: 2 (if they did not exist)
Teams created: 3 (if they did not exist)

Invalid example

csv entity,name,category,league team,Team without league,Senior, foo,Unknown entry,, team,,Senior,Gold team,Team with missing reference,U13,Gold

Expected errors:

team row without league;
invalid entity (foo);
empty name;
non-existing category reference (U13).

Recommended operation flow

1. Download base template. 2. Fill categories and leagues first. 3. Fill teams referencing exact category/league names. 4. Import template. 5. Review creation summary. 6. Retry if errors with corrected data.

Best practices

Keep consistent names (e.g. Youth A, Youth B).
Avoid typographic variants for the same entity.
Load in blocks (simple structure first, then expansions).

Current scope

This import covers:

categories
leagues
teams

Not covered yet:

bulk member assignment
player_profile load
mass update/delete

Troubleshooting

"CSV requires columns: entity,name,category,league"

Header does not match. Verify first row.

"Template has no data"

File has only header or is empty.

"team requires category and league"

Incomplete team row.

"category/league does not exist"

Add creation row in same CSV or create it in app first.