The vast majority of reports in Echoes are organized around teams, making their configuration crucial to using the product.

Teams in Echoes form a tree hierarchy. That is, a Team can have sub-teams and so on. Each Team level is thus an interesting aggregation point for reported efforts. Contributors in your organization should be dispatched into Teams. Contributors can be dispatched at any level of the organization. At any given time, a Contributor is dispatched into one team at most. Otherwise, contributors can be left in the Undispatched Contributors special-team.

To make the best use of Echoes, Teams should reflect a structure that is of importance for you, and Contributors should be dispatched accordingly. Also, companies evolve with time. Thus, work is required to keep Echoes Team and Contributors dispatching up to date.

When a Contributor changes of dispatch Team, we still keep track of the past membership so that the allocation of efforts as seen in the past is correct in your Dashboards.

We provide three main way to configure your Team tree and the Contributor memberships: a manual setup, an Human Resource Information System (HRIS) connector, and CSV imports.

One way to configure Echoes Teams is to manually edit the Team tree hierarchy in a graphical interface. Contributors can be dispatched into teams by manually selecting a team and then browsing the list of known Contributors. This list of known Contributors is built from data observed "in the wild" (for instance, in GitHub Pull-Requests authors).

You may already have an HRIS with all the Team structure and Contributor information. Rather than double-entering the information in your HRIS and then again in Echoes, we propose to configure Echoes to synchronizes periodically with your HRIS. To support a large number of HRIS we embed a third-party connector named Finch from inside Echoes. The setup is as follows: connect your HRIS with Finch, then configure the synchronization in case you want to limit the synchronization to a small number of Teams (for instance, to select only engineering teams).

The HRIS system will then periodically synchronize:

• the Team tree of all subteams selected for synchronizatoin
• the Membership of all these (including name, current Team of attachment, and work email)

Automated synchronization systems can go sideways, in particular we prevent automated large deletions of teams. Such an event could occur because of technical errors, clerical errors in the HRIS, or expected large team re-shuffling. Since Echoes does not have the full-context, we prevent the synchronization resulting in large changes and get alerted if the synchronization is stuck for too long. It is always possible to run a one-off synchronization with a visual preview of the change.

On the Teams page, select the HRIS mode. Then click Install Finch an in-browser window will open and ask you to connect your HRIS. You will need credentials and the specific process may change depending on your specific HRIS solution.





Once connected, you can always re-install Finch and follow the same procedure if your HRIS changes.

When you have a working HRIS connection you can prompt a listing of the Team-tree as Echoes understands it and lets you pick the one you will synchronize automatically. All subteams of a selected Team will also be synchronized.

For instance, in this example, we unselect the "Product" Team because the team has not onboarded on Echoes yet.

We recommend you run a one-off synchronization after connecting or re-configuring an HRIS. The one-off synchronization will show you a summary of the changes that will take place. And if these changes include a lot of Team changes you will be able to notice and adapt the configuration if required.

In the above example we see that removing the "Product" teams actually remove a teams and move their members to the undispatched team (which is not billed).

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.

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

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.



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.

The answer will strongly depend on your adoption-level of Echoes and your typical company changes. If you are merely trying Echoes out, you may be satisfied with the Manual Team edition first. If your HRIS is well maintained and the team-organization up-to-date in it, definitely pick this mode as it requires almost no intervention besides the initial setup. The CSV imports are an in-between but may require some dedicated person to update Echoes periodically.

No. First, very few organizations have a team layout in their GitHub or GitLab organization which maps to reality. Second, Echoes requires the concept of a join date, and keeps track of how a given member of the organization changes teams over time.

Sorry, you've definitely hit a bug and this should not happen. Contact us and we will happily work on fixing the issue.