29min

Teams

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.

Manual configurations of Teams and Memberships

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

A note on duplicated entries

There are situations where a name may appear twice (for instance if bob@echoeshq.com has been contributing under a secondary email sponge@example.com) and Echoes has no way to match these two identities to a single contributor.



This may hurt the readability of your Echoes dashboards and impact your billing. We therefore recommend that some compliance efforts is undertaken to clarify these data issues, or to reach out to support@echoeshq.com for help.

Automated synchronization of an Human Resource Information System (HRIS)

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.

Connecting Finch

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.



Document image



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

Configuring the synchronized teams

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.

Document image

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

Running a one-off synchronization

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.

Document image

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

Batched operations with CSV imports

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
|

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.

Team tree hierarchy after applying the example file
Team tree hierarchy after applying the example file

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.

Text
|

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.

Frequently asked questions

Q: What mode should I use?

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.

Q: Can I import teams from my SCM (e.g., GitHub)?

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.

Q: I upload my CSV, then I upload the same CSV again and Echoes tells me there are changes, what is going on?

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





Updated 15 Mar 2022
Did this page help you?
Yes
No