Skip to main content

📘 CSV Upload (Teams): Fields, Format & Step-by-Step Guide

🚀 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

[email protected]

📌 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.

Did this answer your question?