Importing teams from CSV
Echoes offers to import your Team tree as well as Membership (i.e., Contributors and their Team of dispatch) in two separate CSV files with different formats.
The CSV format may evolve!
The CSV import feature is still considered experimental, therefore the format of both files may continue to evolve.
There is a preview-based import process for both files. However the format and the operations around these CSV files vary a bit. Let's go through this in more details.
The preview-based import only means that you get a chance to review what will occur if we take your CSV into account. This is especially important when clerical errors creep-in.
The process is as follows:
- You upload a CSV file.
- Echoes verifies the content of the file, checks some common clerical errors.
- Echoes compares the content of the CSV file with what we already know and presents you with a list of actions that will occur.
- You review the list of actions and approve or cancel the upload.
- If you approve Echoes goes on and effectively takes the CSV-content into account.
This two step processes, with an extensive set of checks and a summary for you to review brings the required peace of mind before confidently updating your whole company structure in Echoes.
This CSV encodes the Team-tree. It is a direct listing of Teams and their parent Team: each Team in your organization should have one line in the CSV and indicate its parent Team (otherwise, they are attached to the organization root).
Column | Definition |
|---|---|
id | A unique identifier that will uniquely (and forever) allow you to refer to this Team. |
name | A textual name that will be displayed in Echoes dashboards. |
parent-id | The id of the parent Team, if empty, then the parent will be Organization-Root special team. |
The above example will result in the following team hierarchy.
The Team CSV must always reflect the complete hierarchy. If you have three Teams {A,B,C} already configured, and send a CSV with teams {C,D} alone, then both Teams {A,B} will be removed.
When a team gets removed, its contributors are automatically moved to the Undispatched Contributors special team.
The Membership CSV format carries two broad set of related information at once: how are your Contributors dispatched into Teams (so that Echoes distributes the observed effort correctly), and what services handles do they use (so that Echoes recognize the right Contributors).
The Membership CSV works incrementally by adding new information. With this mechanism you do not have to provide all past dispatched Teams or old emails after a company rename when a new member joins your company. Also, this is important because it means that most fields are optional and you will not erase previously-correct information when using the CSV import.
Here is a minimal CSV, for a single Contributor entry, multiple Contributor entries add no more complexity thus let's keep the example short.
Column | Definition |
|---|---|
id | A unique identifier that will uniquely (and forever) allow you to refer to this Contributor. In our example reg:t-1234 could be an internal code from the HR department. |
emails | A space-separated list of email addresses that this Contributor uses. |
name | The textual full name for Display purposes. |
services | A space-separated list of known-services that this Contributor is known to use and that Echoes should recognize (the only two values are gitlab and github at the time of this writing but the list will expand). |
team-id | The team for this Member, the ID must be an id provided in the Team-CSV import. |
start-date | The date at which the Contributor started participating in the team (i.e., this is not the join-date in your company) in YYYY-MM-DD format, leave "empty" to mean "currently" (more below). |
github-username | When services contains github this is the GitHub username that the employee has configured to contribute to the Organization (empty otherwise or if not known). |
gitlab-username | When services contains gitlab this is the GitLab username that the employee has configured to contribute to the Organization (empty otherwise or if not known). |
The services column is redundant so that Echoes knows when to disambiguate the presence/absence of a gitlab-username field as an expected or an unexpected situation worth warning for. For instance, if the services column contains github then the github-username must be non-empty, otherwise it should be empty. If you do not know the GitHub username for a member, then the services column must not contain github.
Echoes attempts to unify already known Contributors using either the id , and email or a given service username. But this process is inherently subject to clerical errors and cannot be perfect, please bear with us and notify us if you hit a roadblock of this kind.
As of today, you cannot reference a team-id for a Team that has been created manually in the Echoes frontend tool (technically you could by fidgeting around but this is not recommended and not officially supported. Thus, you must perform a complete Team CSV import before a Membership CSV can proceed.
The start-date handling when the column is empty is special: it means "currently". Echoes interprets this information with subtlety but in short it means we do the right thing. Note that you can alter past-team memberships with this field.
Multiple lines with a same id . It is valid to provide multiple lines (e.g., to fill-in the Team-history for a given Contributor) for a same Contributor. However some information like emails, names may be different in these lines. In such a situation Echoes does its best, picks one name and the combination of emails. Thus, overall this situation should be a non-issue.