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 preview based imports 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 teams csv format 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) teams csv id,name,parent id team 1,"it","" team 2,"sales","" team 12,"the gentle frontend people",team 1 team 13,"the chad operation team",team 1 team 14,"the backend leprechauns",team 1 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 memberships csv format 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 id,emails,name,services,team id,start date,github username,gitlab username reg\ t 1234,mr\@test com test\@echoeshq com,"monsieur test",github gitlab,team 12,2021 10 01,mrtest,mrtest gitlab 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