🚀 Quick Overview
With the Teams CSV Upload, you can create or update many teams at once.
Each row represents a team (uniquely identified by external_id).
Supported operations: Create and Update
After the import, you’ll see how many teams were created or updated.
🛠️ Before You Start
Permissions: Customer Admin
File format: .csv • Encoding: UTF-8 • Separator: , (comma)
Multiple values: Separate with a pipe | (e.g., TEAM-001|TEAM-002)
Max file size: 32 MB (≈ 150,000 rows possible)
⚠️ Common pitfalls:
Wrong separator ; instead of , → File will be rejected
Unknown column names in the header → File will be rejected
Mismatched column count (header vs. row) → Upload error
parent_teams or users reference entries that don’t exist → Row invalid
📑 Step-by-Step Guide (Teams)
1) Download CSV Template
Open Teams under /app/teams
Click Download CSV Template (top right)
2) Edit the CSV
Open the file in Excel, Google Sheets, or similar
Fill in at least the required columns: external_id and name
If your company does not have predefined external_ids, please number the teams as you wish
Separate multiple values in parent_teams and users with |
Save as CSV (UTF-8, comma-separated)
3) Upload CSV
Go to /app/teams → Upload CSV File
Select your file
(Optional) Enable/disable teams
⚠️ Important: First read the section “Enable/Disable Teams”.
Incorrect use may unintentionally block many teams.
Continue → Review preview:
✅ Green = Valid row
❌ Red = Error (hover for details)
Fix any errors in the CSV and re-upload
Import → Confirmation shows created/updated teams
⚠️ Important: Enable/Disable Teams
When the option “Enable/Disable Teams” is active:
All teams in your CSV will be set to active (even previously blocked ones)
All teams not in the CSV will be blocked
✅ Useful if you’re uploading a full, up-to-date team list
❌ Risky if you’re only creating a few new teams or making small changes
📌 Recommendation: Only enable for full synchronizations. Keep disabled for partial updates.
📋 Column Reference (Teams)
Column | Description (business) | Required | Type | Multiple? | Format / Rules | Example(s) | Common Errors |
external_id | Unique team ID (free choice, for match) | Yes | Text | No | Must be unique per team | TEAM-100 | Missing, duplicate |
name | Team name | Yes | Text | No | Clear, meaningful name | Product Engineering | Missing |
type | Team type/category | No | Text | No | Free (e.g. “Department”, “Squad”) | Department | – |
description | Short description | No | Text | No | Free | Ensures product quality | – |
goal | Team goal | No | Text | No | Free | Improve release cadence | – |
parent_teams | Parent teams (by external_id) | No | Text | Yes | ` | ` separated; each ID must exist (in system or CSV) | TEAM-001 |
users | Members (by email or Staff-ID) | No | Text | Yes | ` | ` separated; each must match an existing user |
📌 Assumption: Staff-ID = Personnel/Employee number maintained in the system (e.g., personal_number).
🧠 Processing Logic
File is processed row by row
Key: external_id (Teams)
If external_id exists → Update
If not → Create
Empty values in non-required fields are allowed (stored as empty)
References must resolve:
parent_teams: every external_id exists in system or same file
users: every email or Staff-ID matches an existing user
❌ Common Error Messages & Fixes (Teams)
“Unsupported delimiter.” → Save file with comma , (not ;)
“The uploaded file contains unsupported fields: …” → Remove/fix unknown columns in header
“The number of fields … does not match the header.” → Check column count per row
“Team with provided external id does not exist …” (parent_teams) → Create parent ID in system or include in CSV
“User not found for value …” (users) → Check email/Staff-ID; user must exist
“Row invalid: required field missing (external_id/name).” → Add required values
📝 Examples
Minimal valid Teams CSV (only required fields):
external_id,name
TEAM-001,Head Office
TEAM-002,Customer Support
📥 Download: Teams_Minimal.csv
Full Teams CSV (all fields):
external_id,name,type,description,goal,parent_teams,users
TEAM-100,Product Engineering,Department,Builds and ships product features,Improve release cadence,TEAM-001,[email protected]|[email protected]|staff_id_42
TEAM-200,QA & Testing,Squad,Ensures product quality,Reduce defect leakage,TEAM-100,[email protected]|staff_id_77
📥 Download: Teams_Full.csv
✅ Pre-Upload Checklist (Teams)
File saved as CSV (UTF-8, comma-separated)
Required columns filled: external_id, name
Multiple values in parent_teams/users separated with |
All referenced parent_teams exist (system or same CSV)
All users (email or Staff-ID) exist
Header spelled correctly, consistent column count per row
File size < 32 MB
❓ FAQ (Teams)
Can I assign multiple parent teams?
→ Yes, separated by | (e.g., TEAM-001|TEAM-050).
How do I assign users?
→ In users, separate emails or Staff-IDs with |. Users must already exist.
Can I deactivate teams?
→ Yes, via Enable/Disable Teams. Warning: Teams not in the CSV will be blocked.
Does column order matter?
→ Yes, follow the template to avoid mismatch errors.
Is there a row limit?
→ Practically up to ~150,000 rows (32 MB). Import runs in batches.